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.
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);
||The context in which to add the new root. Requires request. In a
||(In JS_AddValueRoot and JS_AddNamedValueRoot) The address of the jsval variable to root|
||(In JS_AddStringRoot and JS_AddNamedStringRoot) The address of the JSString* variable to root|
||(In JS_AddObjectRoot and JS_AddNamedObjectRoot) The address of the JSObject* variable to root|
||(In JS_AddGCThingRoot and JS_AddNamedGCThingRoot) The address of the JSString* or JSObject* (not jsval) variable to root|
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
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_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
name parameter, if present and non-null, is stored in the
JSRuntime's root table entry along with
name string's lifetime must last at least until the balancing call to
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.
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