js/public/Zone.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 /* JavaScript API. */
   8
   9 #ifndef js_Zone_h
  10 #define js_Zone_h
  11
  12 #include "mozilla/MemoryReporting.h"  // mozilla::MallocSizeOf
  13
  14 #include <stddef.h>  // size_t
  15
  16 #include "jstypes.h"        // JS_PUBLIC_API
  17 #include "js/RootingAPI.h"  // JS::Handle
  18 #include "js/TypeDecls.h"  // JSContext, JSObject, jsid, JS::Compartment, JS::GCContext, JS::Value, JS::Zone
  19
  20 // [SMDOC] Nested GC Data Structures (Compartments and Zones)
  21 //
  22 // The GC has two nested data structures, Zones and Compartents. Each has
  23 // distint responsibilities. Zones contain compartments, along with other GC
  24 // resources used by a tab. Compartments contain realms, which are specification
  25 // defined.
  26 //
  27 // See also the SMDoc on Realms.
  28 //
  29 // Compartment
  30 // -----------
  31 // Security membrane; when an object from compartment A is used in compartment
  32 // B, a cross-compartment wrapper (a kind of proxy) is used. In the browser,
  33 // same-origin realms can share a compartment.
  34 //
  35 // Zone
  36 // ----
  37 // A Zone is a group of compartments that share GC resources (arenas, strings,
  38 // etc) for memory usage and performance reasons. Zone is the GC unit: the GC
  39 // can operate on one or more zones at a time. The browser uses roughly one zone
  40 // per tab.
  41
  42 using JSDestroyZoneCallback = void (*)(JS::GCContext*, JS::Zone*);
  43
  44 using JSDestroyCompartmentCallback = void (*)(JS::GCContext*, JS::Compartment*);
  45
  46 using JSSizeOfIncludingThisCompartmentCallback =
  47     size_t (*)(mozilla::MallocSizeOf, JS::Compartment*);
  48
  49 extern JS_PUBLIC_API void JS_SetDestroyZoneCallback(
  50     JSContext* cx, JSDestroyZoneCallback callback);
  51
  52 extern JS_PUBLIC_API void JS_SetDestroyCompartmentCallback(
  53     JSContext* cx, JSDestroyCompartmentCallback callback);
  54
  55 extern JS_PUBLIC_API void JS_SetSizeOfIncludingThisCompartmentCallback(
  56     JSContext* cx, JSSizeOfIncludingThisCompartmentCallback callback);
  57
  58 extern JS_PUBLIC_API void JS_SetCompartmentPrivate(JS::Compartment* compartment,
  59                                                    void* data);
  60
  61 extern JS_PUBLIC_API void* JS_GetCompartmentPrivate(
  62     JS::Compartment* compartment);
  63
  64 extern JS_PUBLIC_API void JS_SetZoneUserData(JS::Zone* zone, void* data);
  65
  66 extern JS_PUBLIC_API void* JS_GetZoneUserData(JS::Zone* zone);
  67
  68 extern JS_PUBLIC_API bool JS_RefreshCrossCompartmentWrappers(
  69     JSContext* cx, JS::Handle<JSObject*> obj);
  70
  71 /**
  72  * Mark a jsid after entering a new compartment. Different zones separately
  73  * mark the ids in a runtime, and this must be used any time an id is obtained
  74  * from one compartment and then used in another compartment, unless the two
  75  * compartments are guaranteed to be in the same zone.
  76  */
  77 extern JS_PUBLIC_API void JS_MarkCrossZoneId(JSContext* cx, jsid id);
  78
  79 /**
  80  * If value stores a jsid (an atomized string or symbol), mark that id as for
  81  * JS_MarkCrossZoneId.
  82  */
  83 extern JS_PUBLIC_API void JS_MarkCrossZoneIdValue(JSContext* cx,
  84                                                   const JS::Value& value);
  85
  86 #endif  // js_Zone_h