/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*-
* vim: set ts=8 sts=2 et sw=2 tw=80:
* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
/* JavaScript API. */
#ifndef js_Zone_h
#define js_Zone_h
#include "mozilla/MemoryReporting.h" // mozilla::MallocSizeOf
#include <stddef.h>
// size_t
#include "jstypes.h" // JS_PUBLIC_API
#include "js/RootingAPI.h" // JS::Handle
#include "js/TypeDecls.h" // JSContext, JSObject, jsid, JS::Compartment, JS::GCContext, JS::Value, JS::Zone
// [SMDOC] Nested GC Data Structures (Compartments and Zones)
//
// The GC has two nested data structures, Zones and Compartents. Each has
// distint responsibilities. Zones contain compartments, along with other GC
// resources used by a tab. Compartments contain realms, which are specification
// defined.
//
// See also the SMDoc on Realms.
//
// Compartment
// -----------
// Security membrane; when an object from compartment A is used in compartment
// B, a cross-compartment wrapper (a kind of proxy) is used. In the browser,
// same-origin realms can share a compartment.
//
// Zone
// ----
// A Zone is a group of compartments that share GC resources (arenas, strings,
// etc) for memory usage and performance reasons. Zone is the GC unit: the GC
// can operate on one or more zones at a time. The browser uses roughly one zone
// per tab.
using JSDestroyZoneCallback =
void (*)(JS::GCContext*, JS::Zone*);
using JSDestroyCompartmentCallback =
void (*)(JS::GCContext*, JS::Compartment*);
using JSSizeOfIncludingThisCompartmentCallback =
size_t (*)(mozilla::MallocSizeOf, JS::Compartment*);
extern JS_PUBLIC_API
void JS_SetDestroyZoneCallback(
JSContext* cx, JSDestroyZoneCallback callback);
extern JS_PUBLIC_API
void JS_SetDestroyCompartmentCallback(
JSContext* cx, JSDestroyCompartmentCallback callback);
extern JS_PUBLIC_API
void JS_SetSizeOfIncludingThisCompartmentCallback(
JSContext* cx, JSSizeOfIncludingThisCompartmentCallback callback);
extern JS_PUBLIC_API
void JS_SetCompartmentPrivate(JS::Compartment* compartment,
void* data);
extern JS_PUBLIC_API
void* JS_GetCompartmentPrivate(
JS::Compartment* compartment);
extern JS_PUBLIC_API
void JS_SetZoneUserData(JS::Zone* zone,
void* data);
extern JS_PUBLIC_API
void* JS_GetZoneUserData(JS::Zone* zone);
extern JS_PUBLIC_API
bool JS_RefreshCrossCompartmentWrappers(
JSContext* cx, JS::Handle<JSObject*> obj);
/**
* Mark a jsid after entering a new compartment. Different zones separately
* mark the ids in a runtime, and this must be used any time an id is obtained
* from one compartment and then used in another compartment, unless the two
* compartments are guaranteed to be in the same zone.
*/
extern JS_PUBLIC_API
void JS_MarkCrossZoneId(JSContext* cx, jsid id);
/**
* If value stores a jsid (an atomized string or symbol), mark that id as for
* JS_MarkCrossZoneId.
*/
extern JS_PUBLIC_API
void JS_MarkCrossZoneIdValue(JSContext* cx,
const JS::Value& value);
#endif // js_Zone_h
