This feature is obsolete. Although it is still supported by browsers, its usage is discouraged in new projects. Try to avoid using it.
Remove a value from the innermost current local root scope.
void JS_ForgetLocalRoot(JSContext *cx, void *thing);
||Pointer to the context in which the caller is running. Requires request. In a
||Pointer to the value to be unrooted. This must point to a JSObject, JSString, JSFunction, or jsdouble. It must not be
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
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.