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 (*)(const char* filename, 89 bool isSystemRealm); 90 JS_PUBLIC_API void SetFilenameValidationCallback(FilenameValidationCallback cb); 91 92 } /* namespace JS */ 93 94 #endif // js_Context_h 95