Obsolete since JavaScript 1.8.5
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.
Enter a local root scope.
Syntax
JSBool JS_EnterLocalRootScope(JSContext *cx);
Name | Type | Description |
---|---|---|
cx |
JSContext * |
Pointer to the context. Requires request. In a JS_THREADSAFE build, the caller must be in a request on this JSContext . |
Description
Scoped local root management allows native functions, getter/setters, etc. to avoid calling JS_AddRoot
and JS_RemoveRoot
to manage global roots temporarily.
JS_AddRoot
roots a variable, ensuring that whatever the variable points to at any given moment is protected from GC. By contrast, local root scopes protect newly-created objects, doubles, and strings. There is no need to tell the JS engine about each variable that may point to such a value.
Calling JS_EnterLocalRootScope
and JS_LeaveLocalRootScope
around the body of the native hook protects each object, double, and string created using the same JSContext
from GC. For example:
JSBool my_GetProperty(JSContext *cx, JSObject *obj, jsval id, jsval *vp) { JSBool ok; if (!JS_EnterLocalRootScope(cx)) return JS_FALSE; // This function doesn't need to bother rooting any new objects, // strings, or doubles it creates using cx. Even if JS_GC is // called, these new values will not be collected. ok = my_GetPropertyBody(cx, obj, id, vp); // When we leave the local root scope, this protection ends. New // items created in this local root scope become subject to GC. JS_LeaveLocalRootScope(cx); return ok; }
Note: JS_LeaveLocalRootScope
or JS_LeaveLocalRootScopeWithResult
must be called once for every prior successful call to JS_EnterLocalRootScope
. If JS_EnterLocalRootScope
fails, you must not make the matching JS_LeaveLocalRootScope
call.
Local root scopes do not cover objects that are the result of JSAPI calls like JS_GetProperty
or JS_CallFunction
.
To remove a GC thing from a local root scope (perhaps to save memory), use JS_ForgetLocalRoot
. To determine if a jsval
points to a GC thing, use JSVAL_IS_GCTHING
.