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