JS_DumpNamedRoots

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.

Enumerate all the named roots in a runtime.

Syntax

void
JS_DumpNamedRoots(JSRuntime *rt,
    void (*dump)(const char *name, void *rp, void *data),
    void *data);
Name Type Description
rt JSRuntime * Pointer to a JSRuntime from which to dump named roots.
dump void (*)(const char *, void *, void *) Pointer to function that actually dumps the named roots. This may not be NULL.
data void * A pointer that is passed to dump each time it is called. The JavaScript engine does not read from or write to this pointer at all. It is passed to the dump function unchanged. It may be NULL.

Description

Each call to JS_AddNamedRoot creates a record in a table of named roots maintained by the garbage collector. JS_DumpNamedRoots provides a way for the application to access the contents of that table. It calls the dump function once for each named root in the given runtime rt. In pseudocode:

/* pseudocode explanation of what JS_DumpNamedRoots does */
void JS_DumpNamedRoots(JSRuntime *rt, DumpFn dump, void *data)
{
    for each (root in rt->namedRoots)
        dump(root.name, root.address, data);
}

Callback syntax

dump is a pointer to a function provided by the application. When JS_DumpNamedRoots calls it, it passes three arguments:

Argument Type Description
name const char * The name of the named root.
rp void * A pointer to the rooted variable, array element, or field. This is the pointer that the application passed to JS_AddNamedRoot. It points to a variable, array element, or field of type jsval, JSObject *, JSString *, or jsdouble *.
data void * The data argument that the application passed to JS_DumpNamedRoots.

Example

static void dumpRoot(const char *name, void *addr, void *data)
{
    /* The application may use `data` for anything.  In this
       example, we use it to pass the desired output file. */
    FILE *f = (FILE *) data;

    fprintf(f, "There is a root named '%s' at %p\n", name, addr);
}

int main()
{
    ...
    JS_DumpNamedRoots(rt, dumpRoot, stderr);
    ...
}

See Also