Realm.h (7862B)
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_Realm_h 8 #define js_Realm_h 9 10 #include "js/shadow/Realm.h" // JS::shadow::Realm 11 12 #include "js/GCPolicyAPI.h" 13 #include "js/TypeDecls.h" // forward-declaration of JS::Realm 14 15 /************************************************************************/ 16 17 // [SMDOC] Realms 18 // 19 // Data associated with a global object. In the browser each frame has its 20 // own global/realm. 21 22 namespace js { 23 namespace gc { 24 JS_PUBLIC_API void TraceRealm(JSTracer* trc, JS::Realm* realm, 25 const char* name); 26 } // namespace gc 27 } // namespace js 28 29 namespace JS { 30 class JS_PUBLIC_API AutoRequireNoGC; 31 32 // Each Realm holds a weak reference to its GlobalObject. 33 template <> 34 struct GCPolicy<Realm*> : public NonGCPointerPolicy<Realm*> { 35 static void trace(JSTracer* trc, Realm** vp, const char* name) { 36 if (*vp) { 37 ::js::gc::TraceRealm(trc, *vp, name); 38 } 39 } 40 }; 41 42 // Get the current realm, if any. The ECMAScript spec calls this "the current 43 // Realm Record". 44 extern JS_PUBLIC_API Realm* GetCurrentRealmOrNull(JSContext* cx); 45 46 // Return the compartment that contains a given realm. 47 inline JS::Compartment* GetCompartmentForRealm(Realm* realm) { 48 return shadow::Realm::get(realm)->compartment(); 49 } 50 51 // Return an object's realm. All objects except cross-compartment wrappers are 52 // created in a particular realm, which never changes. Returns null if obj is 53 // a cross-compartment wrapper. 54 extern JS_PUBLIC_API Realm* GetObjectRealmOrNull(JSObject* obj); 55 56 extern JS_PUBLIC_API bool HasRealmInitializedGlobal(Realm* realm); 57 58 // Get the value of the "private data" internal field of the given Realm. 59 // This field is initially null and is set using SetRealmPrivate. 60 // It's a pointer to embeddding-specific data that SpiderMonkey never uses. 61 extern JS_PUBLIC_API void* GetRealmPrivate(Realm* realm); 62 63 // Set the "private data" internal field of the given Realm. 64 extern JS_PUBLIC_API void SetRealmPrivate(Realm* realm, void* data); 65 66 typedef void (*DestroyRealmCallback)(JS::GCContext* gcx, Realm* realm); 67 68 // Set the callback SpiderMonkey calls just before garbage-collecting a realm. 69 // Embeddings can use this callback to free private data associated with the 70 // realm via SetRealmPrivate. 71 // 72 // By the time this is called, the global object for the realm has already been 73 // collected. 74 extern JS_PUBLIC_API void SetDestroyRealmCallback( 75 JSContext* cx, DestroyRealmCallback callback); 76 77 using RealmNameCallback = void (*)(JSContext* cx, Realm* realm, char* buf, 78 size_t bufsize, 79 const JS::AutoRequireNoGC& nogc); 80 81 // Set the callback SpiderMonkey calls to get the name of a realm, for 82 // diagnostic output. 83 extern JS_PUBLIC_API void SetRealmNameCallback(JSContext* cx, 84 RealmNameCallback callback); 85 86 // Get the global object for the given realm. This only returns nullptr during 87 // GC, between collecting the global object and destroying the Realm. 88 extern JS_PUBLIC_API JSObject* GetRealmGlobalOrNull(Realm* realm); 89 90 // Initialize standard JS class constructors, prototypes, and any top-level 91 // functions and constants associated with the standard classes (e.g. isNaN 92 // for Number). 93 extern JS_PUBLIC_API bool InitRealmStandardClasses(JSContext* cx); 94 95 // If the current realm has the non-standard freezeBuiltins option set to true, 96 // freeze the constructor object and seal the prototype. 97 extern JS_PUBLIC_API bool MaybeFreezeCtorAndPrototype(JSContext* cx, 98 HandleObject ctor, 99 HandleObject maybeProto); 100 101 /* 102 * Ways to get various per-Realm objects. All the getters declared below operate 103 * on the JSContext's current Realm. 104 */ 105 106 extern JS_PUBLIC_API JSObject* GetRealmObjectPrototype(JSContext* cx); 107 extern JS_PUBLIC_API JS::Handle<JSObject*> GetRealmObjectPrototypeHandle( 108 JSContext* cx); 109 110 extern JS_PUBLIC_API JSObject* GetRealmFunctionPrototype(JSContext* cx); 111 extern JS_PUBLIC_API JS::Handle<JSObject*> GetRealmFunctionPrototypeHandle( 112 JSContext* cx); 113 114 extern JS_PUBLIC_API JSObject* GetRealmArrayPrototype(JSContext* cx); 115 116 extern JS_PUBLIC_API JSObject* GetRealmErrorPrototype(JSContext* cx); 117 118 extern JS_PUBLIC_API JSObject* GetRealmIteratorPrototype(JSContext* cx); 119 120 extern JS_PUBLIC_API JSObject* GetRealmAsyncIteratorPrototype(JSContext* cx); 121 122 // Returns an object that represents the realm, that can be referred from 123 // other realm/compartment. 124 // See the consumer in `MaybeCrossOriginObjectMixins::EnsureHolder` for details. 125 extern JS_PUBLIC_API JSObject* GetRealmKeyObject(JSContext* cx); 126 127 // Implements https://tc39.github.io/ecma262/#sec-getfunctionrealm 128 // 7.3.22 GetFunctionRealm ( obj ) 129 // 130 // WARNING: may return a realm in a different compartment! 131 // 132 // Will throw an exception and return nullptr when a security wrapper or revoked 133 // proxy is encountered. 134 extern JS_PUBLIC_API Realm* GetFunctionRealm(JSContext* cx, 135 HandleObject objArg); 136 137 /** NB: This API is infallible; a nullptr return value does not indicate error. 138 * 139 * |target| must not be a cross-compartment wrapper because CCWs are not 140 * associated with a single realm. 141 * 142 * Entering a realm roots the realm and its global object until the matching 143 * JS::LeaveRealm() call. 144 */ 145 extern JS_PUBLIC_API JS::Realm* EnterRealm(JSContext* cx, JSObject* target); 146 147 extern JS_PUBLIC_API void LeaveRealm(JSContext* cx, JS::Realm* oldRealm); 148 149 /** 150 * Reset the seed for Math.random() within the current realm. 151 * 152 * Enables embedders to reset the seed at controlled points, e.g. after 153 * resuming execution from an instance snapshot of SpiderMonkey's VM. 154 */ 155 extern JS_PUBLIC_API void ResetRealmMathRandomSeed(JSContext* cx); 156 157 } // namespace JS 158 159 /* 160 * At any time, a JSContext has a current (possibly-nullptr) realm. The 161 * preferred way to change the current realm is with JSAutoRealm: 162 * 163 * void foo(JSContext* cx, JSObject* obj) { 164 * // in some realm 'r' 165 * { 166 * JSAutoRealm ar(cx, obj); // constructor enters 167 * // in the realm of 'obj' 168 * } // destructor leaves 169 * // back in realm 'r' 170 * } 171 * 172 * The object passed to JSAutoRealm must *not* be a cross-compartment wrapper, 173 * because CCWs are not associated with a single realm. 174 * 175 * For more complicated uses that don't neatly fit in a C++ stack frame, the 176 * realm can be entered and left using separate function calls: 177 * 178 * void foo(JSContext* cx, JSObject* obj) { 179 * // in 'oldRealm' 180 * JS::Realm* oldRealm = JS::EnterRealm(cx, obj); 181 * // in the realm of 'obj' 182 * JS::LeaveRealm(cx, oldRealm); 183 * // back in 'oldRealm' 184 * } 185 * 186 * Note: these calls must still execute in a LIFO manner w.r.t all other 187 * enter/leave calls on the context. Furthermore, only the return value of a 188 * JS::EnterRealm call may be passed as the 'oldRealm' argument of 189 * the corresponding JS::LeaveRealm call. 190 * 191 * Entering a realm roots the realm and its global object for the lifetime of 192 * the JSAutoRealm. 193 */ 194 195 class MOZ_RAII JS_PUBLIC_API JSAutoRealm { 196 JSContext* cx_; 197 JS::Realm* oldRealm_; 198 199 public: 200 JSAutoRealm(JSContext* cx, JSObject* target); 201 JSAutoRealm(JSContext* cx, JSScript* target); 202 ~JSAutoRealm(); 203 }; 204 205 class MOZ_RAII JS_PUBLIC_API JSAutoNullableRealm { 206 JSContext* cx_; 207 JS::Realm* oldRealm_; 208 209 public: 210 explicit JSAutoNullableRealm(JSContext* cx, JSObject* targetOrNull); 211 ~JSAutoNullableRealm(); 212 }; 213 214 #endif // js_Realm_h