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);
...
}