JS_Add*Root 编辑

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);

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.

See Also

• MXR ID Search for JS_AddValueRoot
• MXR ID Search for JS_AddStringRoot
• MXR ID Search for JS_AddObjectRoot
• MXR ID Search for JS_AddNamedValueRoot
• MXR ID Search for JS_AddNamedStringRoot
• MXR ID Search for JS_AddNamedObjectRoot
• bug 912581