HeapSnapshot.webidl (3810B)
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 };