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

This article covers features introduced in SpiderMonkey 1.8

DEBUG only. Dump the object graph of heap-allocated things.

Syntax

bool
JS_DumpHeap(JSRuntime *rt, FILE *fp, void* startThing, JSGCTraceKind kind,
            void *thingToFind, size_t maxDepth, void *thingToIgnore);
Name Type Description
cx JSContext * Pointer to a JS context. Every JSContext is permanently associated with a JSRuntime; each JSRuntime contains a GC heap.
fp FILE * File for the dump output.
startThing void * NULL or a pointer to a GC thing (use JS::Value::toGCThing() to obtain a pointer to pass here). When null, dump all things reachable from the runtime roots. When non-null, dump only things reachable from the object indicated.
startKind JSGCTraceKind Trace kind of startThing, if startThing is not null. Must be JSTRACE_OBJECT when startThing is null.
thingToFind void * NULL or a pointer to a GC thing. If this is non-null, JS_DumpHeap only dumps paths in the object graph leading to the specified thing.
maxDepth size_t The upper bound on the number of edges to descend from the graph roots.
thingToIgnore void * NULL or a pointer to a GC thing that will be ignored during graph traversal. 
enum JSGCTraceKind
{
    // These trace kinds have a publicly exposed, although opaque, C++ type.
    // Note: The order here is determined by our Value packing. Other users
    //       should sort alphabetically, for consistency.
    JSTRACE_OBJECT = 0x00,
    JSTRACE_STRING = 0x01,
    JSTRACE_SYMBOL = 0x02,
    JSTRACE_SCRIPT = 0x03,

    // Shape details are exposed through JS_TraceShapeCycleCollectorChildren.
    JSTRACE_SHAPE = 0x04,

    // The kind associated with a nullptr.
    JSTRACE_NULL = 0x06,

    // A kind that indicates the real kind should be looked up in the arena.
    JSTRACE_OUTOFLINE = 0x07,

    // The following kinds do not have an exposed C++ idiom.
    JSTRACE_BASE_SHAPE = 0x0F,
    JSTRACE_JITCODE = 0x1F,
    JSTRACE_LAZY_SCRIPT = 0x2F,
    JSTRACE_TYPE_OBJECT = 0x3F,

    JSTRACE_LAST = JSTRACE_TYPE_OBJECT
};

Description

See bug 378261 for detail.

When tracing a thing, the GC needs to know about the layout of the object it is looking at. There are a fixed number of different layouts that the GC knows about. The "trace kind" is a static map which tells which layout a GC thing has.

Although this map is public, the details are completely hidden. Not all of the matching C++ types are exposed, and those that are, are opaque.

See JS::Value::gcKind() and JSTraceCallback in <codde>Tracer.h</codde> for more details.

See Also