tor-browser

The Tor Browser
git clone https://git.dasho.dev/tor-browser.git
Log | Files | Refs | README | LICENSE

Context.h (4336B)

      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 // Runtime
     27 // -------
     28 // JSRuntime is very similar to JSContext: each runtime belongs to one context
     29 // (thread), but helper threads don't have their own runtimes (they're shared by
     30 // all runtimes in the process and use the runtime of the task they're
     31 // executing).
     32 //
     33 // Note:
     34 // Locking, contexts, and memory allocation.
     35 //
     36 // It is important that SpiderMonkey be initialized, and the first context
     37 // be created, in a single-threaded fashion.  Otherwise the behavior of the
     38 // library is undefined.
     39 // See:
     40 // https://developer.mozilla.org/en-US/docs/Mozilla/Projects/SpiderMonkey/JSAPI_reference
     41 
     42 // Create a new context (and runtime) for this thread.
     43 extern JS_PUBLIC_API JSContext* JS_NewContext(
     44    uint32_t maxbytes, JSRuntime* parentRuntime = nullptr);
     45 
     46 // Destroy a context allocated with JS_NewContext. Must be called on the thread
     47 // that called JS_NewContext.
     48 extern JS_PUBLIC_API void JS_DestroyContext(JSContext* cx);
     49 
     50 JS_PUBLIC_API void* JS_GetContextPrivate(JSContext* cx);
     51 
     52 JS_PUBLIC_API void JS_SetContextPrivate(JSContext* cx, void* data);
     53 
     54 extern JS_PUBLIC_API JSRuntime* JS_GetParentRuntime(JSContext* cx);
     55 
     56 extern JS_PUBLIC_API JSRuntime* JS_GetRuntime(JSContext* cx);
     57 
     58 extern JS_PUBLIC_API void JS_SetFutexCanWait(JSContext* cx);
     59 
     60 namespace js {
     61 
     62 void AssertHeapIsIdle();
     63 
     64 } /* namespace js */
     65 
     66 namespace JS {
     67 
     68 /**
     69 * Asserts (in debug and release builds) that `obj` belongs to the current
     70 * thread's context.
     71 */
     72 JS_PUBLIC_API void AssertObjectBelongsToCurrentThread(JSObject* obj);
     73 
     74 /**
     75 * Install a process-wide callback to validate script filenames. The JS engine
     76 * will invoke this callback for each JS script it parses or XDR decodes.
     77 *
     78 * If the callback returns |false|, an exception is thrown and parsing/decoding
     79 * will be aborted.
     80 *
     81 * See also CompileOptions::setSkipFilenameValidation to opt-out of the callback
     82 * for specific parse jobs.
     83 */
     84 using FilenameValidationCallback = bool (*)(JSContext* cx,
     85                                            const char* filename);
     86 JS_PUBLIC_API void SetFilenameValidationCallback(FilenameValidationCallback cb);
     87 
     88 /**
     89 * Install an context wide callback that implements the ECMA262 specification
     90 * host hook `HostEnsureCanAddPrivateElement`.
     91 *
     92 * This hook, which should only be overriden for Web Browsers, examines the
     93 * provided object to determine if the addition of a private field is allowed,
     94 * throwing an exception and returning false if not.
     95 *
     96 * The default implementation of this hook, which will be used unless overriden,
     97 * examines only proxy objects, and throws if the proxy handler returns true
     98 * from the handler method `throwOnPrivateField()`.
     99 */
    100 using EnsureCanAddPrivateElementOp = bool (*)(JSContext* cx, HandleValue val);
    101 
    102 JS_PUBLIC_API void SetHostEnsureCanAddPrivateElementHook(
    103    JSContext* cx, EnsureCanAddPrivateElementOp op);
    104 
    105 /**
    106 * Transition the cx to a mode where failures that would normally cause a false
    107 * return value will instead crash with a diagnostic assertion.
    108 *
    109 * Return value: the former brittle mode setting.
    110 */
    111 JS_PUBLIC_API bool SetBrittleMode(JSContext* cx, bool setting);
    112 
    113 class AutoBrittleMode {
    114  bool wasBrittle;
    115  JSContext* cx;
    116 
    117 public:
    118  explicit AutoBrittleMode(JSContext* cx) : cx(cx) {
    119    wasBrittle = SetBrittleMode(cx, true);
    120  }
    121  ~AutoBrittleMode() { MOZ_ALWAYS_TRUE(SetBrittleMode(cx, wasBrittle)); }
    122 };
    123 
    124 } /* namespace JS */
    125 
    126 #endif  // js_Context_h