js/public/Context.h

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*-
   2  * vim: set ts=8 sts=2 et sw=2 tw=80:
   3  * This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 /* JavaScript API. */
   8
   9 #ifndef js_Context_h
  10 #define js_Context_h
  11
  12 #include "jspubtd.h"
  13 // [SMDOC] Nested Thread Data Structures (JSContext, JSRuntime)
  14 //
  15 // Spidermonkey has two nested data structures for representing threads,
  16 // JSContext and JSRuntime. All JS threads are represented by a context.
  17 // Contexts can contain runtimes. A runtime however is not present for
  18 // all threads. Threads also interact with the GC. See "Nested GC
  19 // DataStructures" for more info.
  20 //
  21 // Context
  22 // -------
  23 // JSContext represents a thread: there must be exactly one JSContext for each
  24 // thread running JS/Wasm.
  25 //
  26 // Internally, helper threads can also have a JSContext. They do not always have
  27 // an active context, but one may be requested by AutoSetHelperThreadContext,
  28 // which activates a pre-allocated JSContext for the duration of its lifetime.
  29 //
  30 // Runtime
  31 // -------
  32 // JSRuntime is very similar to JSContext: each runtime belongs to one context
  33 // (thread), but helper threads don't have their own runtimes (they're shared by
  34 // all runtimes in the process and use the runtime of the task they're
  35 // executing).
  36 //
  37 // Note:
  38 // Locking, contexts, and memory allocation.
  39 //
  40 // It is important that SpiderMonkey be initialized, and the first context
  41 // be created, in a single-threaded fashion.  Otherwise the behavior of the
  42 // library is undefined.
  43 // See:
  44 // https://developer.mozilla.org/en-US/docs/Mozilla/Projects/SpiderMonkey/JSAPI_reference
  45
  46 // Create a new context (and runtime) for this thread.
  47 extern JS_PUBLIC_API JSContext* JS_NewContext(
  48     uint32_t maxbytes, JSRuntime* parentRuntime = nullptr);
  49
  50 // Destroy a context allocated with JS_NewContext. Must be called on the thread
  51 // that called JS_NewContext.
  52 extern JS_PUBLIC_API void JS_DestroyContext(JSContext* cx);
  53
  54 JS_PUBLIC_API void* JS_GetContextPrivate(JSContext* cx);
  55
  56 JS_PUBLIC_API void JS_SetContextPrivate(JSContext* cx, void* data);
  57
  58 extern JS_PUBLIC_API JSRuntime* JS_GetParentRuntime(JSContext* cx);
  59
  60 extern JS_PUBLIC_API JSRuntime* JS_GetRuntime(JSContext* cx);
  61
  62 extern JS_PUBLIC_API void JS_SetFutexCanWait(JSContext* cx);
  63
  64 namespace js {
  65
  66 void AssertHeapIsIdle();
  67
  68 } /* namespace js */
  69
  70 namespace JS {
  71
  72 /**
  73  * Asserts (in debug and release builds) that `obj` belongs to the current
  74  * thread's context.
  75  */
  76 JS_PUBLIC_API void AssertObjectBelongsToCurrentThread(JSObject* obj);
  77
  78 /**
  79  * Install a process-wide callback to validate script filenames. The JS engine
  80  * will invoke this callback for each JS script it parses or XDR decodes.
  81  *
  82  * If the callback returns |false|, an exception is thrown and parsing/decoding
  83  * will be aborted.
  84  *
  85  * See also CompileOptions::setSkipFilenameValidation to opt-out of the callback
  86  * for specific parse jobs.
  87  */
  88 using FilenameValidationCallback = bool (*)(JSContext* cx,
  89                                             const char* filename);
  90 JS_PUBLIC_API void SetFilenameValidationCallback(FilenameValidationCallback cb);
  91
  92 /**
  93  * Install an context wide callback that implements the ECMA262 specification
  94  * host hook `HostEnsureCanAddPrivateElement`.
  95  *
  96  * This hook, which should only be overriden for Web Browsers, examines the
  97  * provided object to determine if the addition of a private field is allowed,
  98  * throwing an exception and returning false if not.
  99  *
 100  * The default implementation of this hook, which will be used unless overriden,
 101  * examines only proxy objects, and throws if the proxy handler returns true
 102  * from the handler method `throwOnPrivateField()`.
 103  */
 104 using EnsureCanAddPrivateElementOp = bool (*)(JSContext* cx, HandleValue val);
 105
 106 JS_PUBLIC_API void SetHostEnsureCanAddPrivateElementHook(
 107     JSContext* cx, EnsureCanAddPrivateElementOp op);
 108
 109 } /* namespace JS */
 110
 111 #endif  // js_Context_h