|
|
Summary
Adds a garbage collection hash table entry for a named JS item to protect it from garbage collection.
|
Syntax
JSBool JS_AddNamedRoot(JSContext *cx, void *rp,
const char *name);
| Name | Type | Description |
|---|
cx | JSContext * | Pointer to a JS context from which to derive runtime information.
|
rp | void * | Pointer to the item to protect.
|
name | char * | Name of the item to protect
|
|
Description
JS_AddNamedRoot protects the GC thing pointed at by a specified pointer, *rp, from garbage collection. rp is a pointer to a pointer to a JS double, string, or object. An entry for rp is added to the garbage collector's table for the JSRuntime of the specified JSContext, cx.
If the GC thing pointed to by *rp is an object, then any GC things reachable from it's properties are automatically protected from garbage collection, too.
The name parameter is stored in the JSRuntime's root table entry along with rp. The name string's lifetime must be at least as long as the JSRuntime's. 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.
|
Notes
You should use JS_AddNamedRoot to root only JS objects, JS strings, or JS doubles, and then only if they are derived from calls to their respective JS_NewXXX creation functions.
If the entry in the root table is successfully created, JS_AddNamedRoot returns JS_TRUE. Otherwise it reports an out of memory error and returns JS_FALSE. *rp may also be a jsval. If JSVAL_IS_GCTHING evaluates to true for that value, then the GC thing will be protected.
|
See Also
|