GlobalObject.h (3950B)
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 #ifndef js_GlobalObject_h 8 #define js_GlobalObject_h 9 10 #include "jstypes.h" 11 12 #include "js/TypeDecls.h" 13 14 class JS_PUBLIC_API JSTracer; 15 16 struct JSClassOps; 17 18 extern JS_PUBLIC_API bool JS_IsGlobalObject(JSObject* obj); 19 20 namespace JS { 21 22 class JS_PUBLIC_API RealmOptions; 23 24 /** 25 * Get the current realm's global. Returns nullptr if no realm has been 26 * entered. 27 */ 28 extern JS_PUBLIC_API JSObject* CurrentGlobalOrNull(JSContext* cx); 29 30 /** 31 * Get the global object associated with an object's realm. The object must not 32 * be a cross-compartment wrapper (because CCWs are shared by all realms in the 33 * compartment). 34 */ 35 extern JS_PUBLIC_API JSObject* GetNonCCWObjectGlobal(JSObject* obj); 36 37 /** 38 * During global creation, we fire notifications to callbacks registered 39 * via the Debugger API. These callbacks are arbitrary script, and can touch 40 * the global in arbitrary ways. When that happens, the global should not be 41 * in a half-baked state. But this creates a problem for consumers that need 42 * to set slots on the global to put it in a consistent state. 43 * 44 * This API provides a way for consumers to set slots atomically (immediately 45 * after the global is created), before any debugger hooks are fired. It's 46 * unfortunately on the clunky side, but that's the way the cookie crumbles. 47 * 48 * If callers have no additional state on the global to set up, they may pass 49 * |FireOnNewGlobalHook| to JS_NewGlobalObject, which causes that function to 50 * fire the hook as its final act before returning. Otherwise, callers should 51 * pass |DontFireOnNewGlobalHook|, which means that they are responsible for 52 * invoking JS_FireOnNewGlobalObject upon successfully creating the global. If 53 * an error occurs and the operation aborts, callers should skip firing the 54 * hook. But otherwise, callers must take care to fire the hook exactly once 55 * before compiling any script in the global's scope (we have assertions in 56 * place to enforce this). This lets us be sure that debugger clients never miss 57 * breakpoints. 58 */ 59 enum OnNewGlobalHookOption { FireOnNewGlobalHook, DontFireOnNewGlobalHook }; 60 61 } // namespace JS 62 63 extern JS_PUBLIC_API JSObject* JS_NewGlobalObject( 64 JSContext* cx, const JSClass* clasp, JSPrincipals* principals, 65 JS::OnNewGlobalHookOption hookOption, const JS::RealmOptions& options); 66 /** 67 * Spidermonkey does not have a good way of keeping track of what compartments 68 * should be marked on their own. We can mark the roots unconditionally, but 69 * marking GC things only relevant in live compartments is hard. To mitigate 70 * this, we create a static trace hook, installed on each global object, from 71 * which we can be sure the compartment is relevant, and mark it. 72 * 73 * It is still possible to specify custom trace hooks for global object classes. 74 * They can be provided via the RealmOptions passed to JS_NewGlobalObject. 75 */ 76 extern JS_PUBLIC_API void JS_GlobalObjectTraceHook(JSTracer* trc, 77 JSObject* global); 78 79 namespace JS { 80 81 /** 82 * This allows easily constructing a global object without having to deal with 83 * JSClassOps, forgetting to add JS_GlobalObjectTraceHook, or forgetting to call 84 * JS::InitRealmStandardClasses(). Example: 85 * 86 * const JSClass globalClass = { "MyGlobal", JSCLASS_GLOBAL_FLAGS, 87 * &JS::DefaultGlobalClassOps }; 88 * JS_NewGlobalObject(cx, &globalClass, ...); 89 */ 90 extern JS_PUBLIC_DATA const JSClassOps DefaultGlobalClassOps; 91 92 } // namespace JS 93 94 extern JS_PUBLIC_API void JS_FireOnNewGlobalObject(JSContext* cx, 95 JS::HandleObject global); 96 97 #endif // js_GlobalObject_h