JavaScript-1.5 Reference

JS_AddRoot Function

Summary

Adds a garbage collection hash table entry for a specified JS item to protect it from garbage collection.

Syntax

JSBool JS_AddRoot(JSContext *cx, void *rp);
NameTypeDescription
cxJSContext *Pointer to a JS context from which to derive runtime information.
rpvoid *Pointer to the item to protect.

Description

JS_AddRoot 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.

Notes

You should use JS_AddRoot 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_AddRoot 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

Groups [ Function ]
Documents [ LXR ID Search ]
Entries [ JSVAL_IS_GCTHING | JS_AddNamedRoot | JS_DumpNamedRoots | JS_RemoveRoot ]

This page was generated by APIDOC