JS::Add*Root

Obsolete since JSAPI 38
This feature is obsolete. Although it may still work in some browsers, its use is discouraged since it could be removed at any time. Try to avoid using it.

This article covers features introduced in SpiderMonkey 31

Register a variable as a member of the garbage collector's root set, to protect anything the root points at from garbage collection.

These functions are obsoleted, use JS::PersistentRooted instead.

Syntax

bool
JS::AddValueRoot(JSContext *cx, JS::Heap<JS::Value> *vp);
bool
JS::AddStringRoot(JSContext *cx, JS::Heap<JSString *> *rp);
bool
JS::AddObjectRoot(JSContext *cx, JS::Heap<JSObject *> *rp);
bool
JS::AddNamedValueRoot(JSContext *cx, JS::Heap<JS::Value> *vp,
                      const char *name);
bool
JS::AddNamedValueRootRT(JSRuntime *rt, JS::Heap<JS::Value> *vp,
                        const char *name);
bool
JS::AddNamedStringRoot(JSContext *cx, JS::Heap<JSString *> *rp,
                       const char *name);
bool
JS::AddNamedObjectRoot(JSContext *cx, JS::Heap<JSObject *> *rp,
                       const char *name);
bool
JS::AddNamedScriptRoot(JSContext *cx, JS::Heap<JSScript *> *rp,
                       const char *name);
Name Type Description
cx JSContext * The context in which to add the new root. Requires request. In a JS_THREADSAFE build, the caller must be in a request on this JSContext.
rt JSRuntime * The runtime in which to add the new root.
vp JS::Heap<JS::Value> The address of the JS::Value variable to root.
rp JS::Heap<JSString *> The address of the JSString * variable to root.
rp JS::Heap<JSObject *> The address of the JSObject * variable to root.
rp JS::Heap<JSScript *> The address of the JSScript * variable to root.
name const char * The name of the new root, or NULL.

Description

The JS::Add*Root and functions add a C/C++ variable to the garbage collector's root set, the set of variables used as starting points each time the collector checks to see what memory is reachable. The garbage collector aggressively collects and recycles memory that it deems unreachable, so roots are often necessary to protect data from being prematurely collected.

vp/rp is the address of a C/C++ variable (or field, or array element) of type JS::Value, JSString *, JSObject *, or JSScript *. This variable must already be initialized. (For example, it must not be an uninitialized local variable. That could cause sporadic crashes during garbage collection, which can be hard to debug.) The variable must remain in memory until the balancing call to JS::Remove*Root. Note that this means that if the root is meant to live past the end of a function, the address of a local (stack-based) variable may not be used for vp/rp. If JS::Add*Root succeeds, then as long as this variable points to a JavaScript value or pointer to GC-thing, that value/GC-thing is protected from garbage collection. If the variable points to an object, then any memory reachable from its properties is automatically protected from garbage collection, too.

An entry for rp is added to the garbage collector's root set for the JSRuntime associated with cx (or, in JS::AddNamedValueRootRT, the runtime rt). The name parameter, if present and non-null, is stored in the JSRuntime's root table entry along with rp. The name string's lifetime must last at least until the balancing call to JS::Remove*Root. Typically name is a static string constant, identifying the source location of the call to JS::AddNamed*Root for debugging purposes.

Needs the Example for typical usage of the name parameter.

All the JS::Add*Root methods are idempotent: multiple calls for the same address will add only one root. Correspondingly, only a single JS::Remove*Root is required to unroot the location.

On success, these functions return true. Otherwise they report an out of memory error and return false.

See Also

Document Tags and Contributors

Tags: 
 Contributors to this page: arai, kscarfone
 Last updated by: arai,