dom/chrome-webidl/HeapSnapshot.webidl

   1 /* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this file,
   4  * You can obtain one at http://mozilla.org/MPL/2.0/.
   5  */
   6
   7 /**
   8  * A HeapSnapshot represents a snapshot of the heap graph
   9  */
  10 [ChromeOnly, Exposed=(Window,Worker)]
  11 interface HeapSnapshot {
  12   /**
  13    * A time stamp of when the heap snapshot was taken, if available. Units are
  14    * microseconds since midnight (00:00:00) 1 January 1970 UTC.
  15    */
  16   readonly attribute unsigned long long? creationTime;
  17
  18   /**
  19    * Take a census of the heap snapshot.
  20    *
  21    * This is the same as |Debugger.Memory.prototype.takeCensus|, but operates on
  22    * the offline heap snapshot's serialized heap graph rather than the live heap
  23    * graph. The same optional configuration options that can be passed to that
  24    * function can be passed here.
  25    *
  26    * The returned value is determined by the `"breakdown"` option used, and is
  27    * usually a `Map`, `Object`, or `Array`. For example, the following breakdown
  28    *
  29    *     {
  30    *       by: "coarseType",
  31    *       objects: { by: "objectClass" },
  32    *       other:   { by: "internalType" }
  33    *     }
  34    *
  35    * produces a result like this:
  36    *
  37    *     {
  38    *       "objects": {
  39    *         "Function":         { "count": 404, "bytes": 37328 },
  40    *         "Object":           { "count": 11,  "bytes": 1264 },
  41    *         "Debugger":         { "count": 1,   "bytes": 416 },
  42    *         "ScriptSource":     { "count": 1,   "bytes": 64 },
  43    *         // ... omitted for brevity...
  44    *       },
  45    *       "scripts":            { "count": 1,   "bytes": 0 },
  46    *       "strings":            { "count": 701, "bytes": 49080 },
  47    *       "other": {
  48    *         "js::Shape":        { "count": 450, "bytes": 0 },
  49    *         "js::BaseShape":    { "count": 21,  "bytes": 0 },
  50    *         "js::ObjectGroup":  { "count": 17,  "bytes": 0 }
  51    *       }
  52    *     }
  53    *
  54    * See the `takeCensus` section of the `js/src/doc/Debugger/Debugger.Memory.md`
  55    * file for detailed documentation.
  56    */
  57   [Throws]
  58   any takeCensus(object? options);
  59
  60   /**
  61    * Describe `node` with the specified `breakdown`. See the comment above
  62    * `takeCensus` or `js/src/doc/Debugger/Debugger.Memory.md` for detailed
  63    * documentation on breakdowns.
  64    *
  65    * Throws an error when `node` is not the id of a node in the heap snapshot,
  66    * or if the breakdown is invalid.
  67    */
  68   [Throws]
  69   any describeNode(object breakdown, NodeId node);
  70
  71   /**
  72    * Compute the dominator tree for this heap snapshot.
  73    *
  74    * @see DominatorTree.webidl
  75    */
  76   [Throws]
  77   DominatorTree computeDominatorTree();
  78
  79   /**
  80    * Find the shortest retaining paths from the node associated with the ID
  81    * `start` to each node associated with the IDs in `targets`. Find at most
  82    * `maxNumPaths` retaining paths for each target node.
  83    *
  84    * The return value is a Map object mapping from each target node ID to an
  85    * array of retaining paths. The array may be empty if we did not find any
  86    * retaining paths.
  87    *
  88    * A path is an array of objects of the form:
  89    *
  90    *     {
  91    *         predecessor: <node ID>,
  92    *         edge: <string or null>,
  93    *     }
  94    *
  95    * The first `predecessor` will always be `start`. The last edge in the path
  96    * leads to the `target` node that is mapped to the path; the `target` does
  97    * not appear as a `predecessor` in the path.
  98    *
  99    * Throws when `start` or any of the elements of `targets` are not an ID of a
 100    * node in the snapshot, or if we encounter an out of memory exception.
 101    */
 102   [Throws]
 103   object computeShortestPaths(NodeId start, sequence<NodeId> targets,
 104                               unsigned long long maxNumPaths);
 105 };