JS ForgetLocalRoot

From MDC

Remove a value from the innermost current local root scope.

[edit] 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.

[edit] 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(n²) 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.

[edit] See Also

LXR ID Search for JS_ForgetLocalRoot

JSVAL_IS_GCTHING, JS_LeaveLocalRootScope JS_LeaveLocalRootScopeWithResult