Obsolete since JSAPI 19
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.

Perform some action for each object in a JSRuntime's GC root set.

Syntax

uint32
JS_MapGCRoots(JSRuntime *rt, JSGCRootMapFun map, void *data);

Callback syntax

#define JS_MAP_GCROOT_NEXT      0       /* continue mapping entries */
#define JS_MAP_GCROOT_STOP      1       /* stop mapping entries */
#define JS_MAP_GCROOT_REMOVE    2       /* remove and free the current entry */

typedef int (*JSGCRootMapFun)(void *rp, const char *name, void *data);

Description

Call JS_MapGCRoots to map the GC's roots table using map(rp, name, data). The root is pointed at by rp; if the root is unnamed, name is null; data is supplied from the third parameter to JS_MapGCRoots.

The map function should return JS_MAP_GCROOT_REMOVE to cause the currently enumerated root to be removed. To stop enumeration, return JS_MAP_GCROOT_STOP. To continue mapping, return JS_MAP_GCROOT_NEXT. These constants are flags; you can OR them together.

This function acquires and releases rt's GC lock around the mapping of the roots table, so the map function should run to completion in as few cycles as possible. The map function cannot call JS_GC, JS_MaybeGC, JS_BeginRequest, or any JS API entry point that acquires locks, without double-tripping or deadlocking on the GC lock.

JS_MapGCRoots returns the count of roots that were successfully mapped.

See Also