Proposed ubi::Node core dump API

IUbiCoreDump.idl

/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsISupports.idl"
#include "nsIFile.idl"

[scriptable, uuid(bitter-hatred-towards-all-that-is-good-and-decent)]
interface IUbiCoreDump : nsISupports
{
    // Populate this core dump object by parsing a JavaScript core dump from
    // |stream|.
    void InitFromStream(in nsIInputStream stream);

    // Conduct a census of the core dump, as documented for
    // Debugger.Memory.prototype.takeCensus.
    [implicit_jscontext]
    jsval takeCensus();

    // Return an array describing one of the shortest paths of GC heap edges
    // from |start| to |target|, or |undefined| if |target| is unreachable from
    // |start|.
    //
    // Each element of the array is either of the form:
    //
    //   { node: <object or string>, edge: <string describing edge from node> }
    //
    // if the node is a JavaScript object or value; or of the form:
    //
    //   { type: <string describing node>, edge: <string describing edge> }
    //
    // if the node is some internal thing that is not a proper JavaScript value
    // (like a shape or a scope chain element). The destination of the i'th
    // array element's edge is the node of the i+1'th array element; the
    // destination of the last array element is implicitly |target|.
    [implicit_jscontext]
    jsval findPath(in jsval start, in jsval target);
};


[scriptable, uuid(insipid-good-cheer-enabled-only-by-stark-ignorance)]
interface IUbiCoreDumpService : nsISupports
{
    // Write a core dump to |file|, as restricted by |boundaries|. |Boundaries|
    // must be a JavaScript object whose properties specify what portion of the
    // ubi::Node graph to write. The recognized properties are:
    //
    //   globals: [ global, ...]
    //     Dump only ubi::Nodes that either:
    //     - belong to the compartments of the given globals;
    //     - belong to no compartment, but do belong to a Zone that contains
    //       one of the given globals;
    //     - are referred to directly by one of the upper two kinds of Node; or
    //     - are the fictional root node, described below.
    //
    //   debuggees: Debugger object
    //     Like 'compartments', but use the debuggees of the given Debugger
    //     object. (Based on some JS::dbg::GetDebuggees API.)
    //
    //   runtime: true
    //     Dump the entire ubi::Node graph, starting with the JSRuntime's roots.
    //
    // One of these properties must be present.
    //
    // The root of the dumped graph is a fictional node whose ubi::Node type
    // name is "CoreDumpRoot". If we are dumping the entire ubi::Node graph,
    // this root node has an edge for each of the JSRuntime's roots. If we are
    // dumping a selected set of globals, the root has an edge to each global,
    // and an edge for each incoming JS reference to the selected Zones.
    [implicit_jscontext]
    void dumpCore(in nsIFile file, jsval boundaries);
};