Obsolete since JSAPI 31
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.
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
JSBool JS_AddValueRoot(JSContext *cx, jsval *vp); JSBool JS_AddStringRoot(JSContext *cx, JSString **spp); JSBool JS_AddObjectRoot(JSContext *cx, JSObject **opp); JSBool JS_AddGCThingRoot(JSContext *cx, void **rp); JSBool JS_AddNamedValueRoot(JSContext *cx, jsval *vp, const char *name); JSBool JS_AddNamedStringRoot(JSContext *cx, JSString **spp, const char *name); JSBool JS_AddNamedObjectRoot(JSContext *cx, JSObject **opp, const char *name); JSBool JS_AddNamedGCThingRoot(JSContext *cx, void **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. |
vp |
jsval * |
(In JS_AddValueRoot and JS_AddNamedValueRoot) The address of the jsval variable to root |
| spp | JSString ** |
(In JS_AddStringRoot and JS_AddNamedStringRoot) The address of the JSString* variable to root |
| opp | JSObject ** |
(In JS_AddObjectRoot and JS_AddNamedObjectRoot) The address of the JSObject* variable to root |
| rp | void ** |
(In JS_AddGCThingRoot and JS_AddNamedGCThingRoot) The address of the JSString* or JSObject* (not jsval) variable to root |
name |
const char * |
(in JS_AddNamedRoot and JS_AddNamedRootRT) 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/spp/opp/rp is the address of a C/C++ variable (or field, or array element) of type JSString *, JSObject *, or jsval. 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_RemoveRoot. 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 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.
JS_AddGCThingRoot allows the caller to have a single root that may hold either strings or objects. A jsval is not a GC-thing (it has tag bits and may be a different size altogether) and thus the address of a jsval variable must not be passed to JS_AddGCThingRoot.
Do not pass a pointer to a JS string or object to any of these functions—rp must point to a variable, the location of the pointer itself, and not an object or string.
An entry for rp is added to the garbage collector's root set for the JSRuntime associated with cx (or, in JS_AddNamedRootRT, 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_RemoveRoot. Typically name is a static string constant, identifying the source location of the call to JS_AddNamedRoot for debugging purposes. JS_DumpNamedRoots can be used to access this information from a debugger.
All the JS_Add*Root methods are idempotent: multiple calls for the same address will add only one root. Correspondingly, only a single JS_RemoveRoot is required to unroot the location.
On success, these functions return JS_TRUE. Otherwise they report an out of memory error and return JS_FALSE.