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.