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.
Remove a value from the innermost current local root scope.
Syntax
void JS_ForgetLocalRoot(JSContext *cx, void *thing);
| Name | Type | Description |
|---|---|---|
cx |
JSContext * |
Pointer to the context in which the caller is running. Requires request. In a JS_THREADSAFE build, the caller must be in a request on this JSContext. |
thing |
void * |
Pointer to the value to be unrooted. This must point to a JSObject, JSString, JSFunction, or jsdouble. It must not be NULL. |
Description
This function is used to interact with scoped local root management. See JS_EnterLocalRootScope for more on this topic.
In case a native hook allocates many objects or other GC-things, but the native protects some of those GC-things by storing them as property values in an object that is itself protected, the hook can call JS_ForgetLocalRoot to free the local root automatically pushed for the now-protected GC-thing. (Here the term GC-thing refers to any value that is subject to garbage collection: a JSObject, JSString, JSFunction, or jsdouble.)
JS_ForgetLocalRoot works on any GC-thing allocated in the current local root scope, but it's more time-efficient when called on references to more recently created GC-things. Calling it successively on other than the most recently allocated GC-thing will tend to average the time inefficiency, and may risk O(n2) growth rate, but in any event, you shouldn't allocate too many local roots if you can root as you go (build a tree of objects from the top down, forgetting each latest-allocated GC-thing immediately upon linking it to its parent).
If the caller is not in any local root scope, JS_ForgetLocalRoot has no effect.