index.rst (12245B)
1 =============== 2 Debugger.Memory 3 =============== 4 5 The :doc:`Debugger API <../index>` can help tools observe the debuggee’s memory use in various ways: 6 7 8 - It can mark each new object with the JavaScript call stack at which it was allocated. 9 10 - It can log all object allocations, yielding a stream of JavaScript call stacks at which allocations have occurred. 11 12 - It can compute a *census* of items belonging to the debuggee, categorizing items in various ways, and yielding item counts. 13 14 15 If *dbg* is a :doc:`Debugger <../debugger/index>` instance, then the methods and accessor properties of ``dbg.memory`` control how *dbg* observes its debuggees’ memory use. The ``dbg.memory`` object is an instance of ``Debugger.Memory``; its inherited accessors and methods are described below. 16 17 18 Allocation Site Tracking 19 ************************ 20 21 The JavaScript engine marks each new object with the call stack at which it was allocated, if: 22 23 24 - the object is allocated in the scope of a global object that is a debuggee of some :doc:`Debugger <../debugger/index>` instance *dbg*; and 25 26 - :ref:`dbg.memory.trackingAllocationSites <debugger-api-debugger-memory-tracking-allocation-sites>` is set to ``true``. 27 28 - A `Bernoulli trial <https://en.wikipedia.org/wiki/Bernoulli_trial>`_ succeeds, with probability equal to the maximum of :ref:`d.memory.allocationSamplingProbability <debugger-api-debugger-memory-alloc-sampling-probability>` of all ``Debugger`` instances ``d`` that are observing the global that this object is allocated within the scope of. 29 30 31 Given a :doc:`Debugger.Object <../debugger.object/index>` instance *dobj* referring to some object, :ref:`dobj.allocationSite <debugger-api-debugger-object-allocation-site>` returns a saved call stack indicating where *dobj*’s referent was allocated. 32 33 34 Allocation Logging 35 ****************** 36 37 If *dbg* is a :doc:`Debugger <../debugger/index>` instance, and :ref:`dbg.memory.trackingAllocationSites <debugger-api-debugger-memory-tracking-allocation-sites>` is set to ``true``, then the JavaScript engine logs each object allocated by *dbg*’s debuggee code. You can retrieve the current log by calling *dbg.memory.drainAllocationsLog*. You can control the limit on the log’s size by setting :ref:`dbg.memory.maxAllocationsLogLength <debugger-api-debugger-memory-max-alloc-log>`. 38 39 40 Censuses 41 ******** 42 43 A *census* is a complete traversal of the graph of all reachable memory items belonging to a particular ``Debugger``‘s debuggees. It produces a count of those items, broken down by various criteria. If *dbg* is a :doc:`Debugger <../debugger/index>` instance, you can call *dbg.memory.takeCensus* to conduct a census of its debuggees’ possessions. 44 45 46 Accessor Properties of the ``Debugger.Memory.prototype`` Object 47 *************************************************************** 48 49 If *dbg* is a :doc:`Debugger <../debugger/index>` instance, then ``dbg.memory`` is a ``Debugger.Memory`` instance, which inherits the following accessor properties from its prototype: 50 51 52 .. _debugger-api-debugger-memory-tracking-allocation-sites: 53 54 ``trackingAllocationSites`` 55 56 A boolean value indicating whether this ``Debugger.Memory`` instance is capturing the JavaScript execution stack when each Object is allocated. This accessor property has both a getter and setter: assigning to it enables or disables the allocation site tracking. Reading the accessor produces ``true`` if the Debugger is capturing stacks for Object allocations, and ``false`` otherwise. Allocation site tracking is initially disabled in a new Debugger. 57 58 Assignment is fallible: if the Debugger cannot track allocation sites, it throws an ``Error`` instance. 59 60 You can retrieve the allocation site for a given object with the :ref:`Debugger.Object.prototype.allocationSite <debugger-api-debugger-object-allocation-site>` accessor property. 61 62 63 .. _debugger-api-debugger-memory-alloc-sampling-probability: 64 65 ``allocationSamplingProbability`` 66 67 A number between 0 and 1 that indicates the probability with which each new allocation should be entered into the allocations log. 0 is equivalent to “never”, 1 is “always”, and .05 would be “one out of twenty”. 68 69 The default is 1, or logging every allocation. 70 71 Note that in the presence of multiple ``Debugger`` instances observing the same allocations within a global’s scope, the maximum ``allocationSamplingProbability`` of all the ``Debugger`` is used. 72 73 74 .. _debugger-api-debugger-memory-max-alloc-log: 75 76 ``maxAllocationsLogLength`` 77 78 The maximum number of allocation sites to accumulate in the allocations log at a time. This accessor can be both fetched and stored to. Its default value is ``5000``. 79 80 81 .. _debugger-api-debugger-memory-alloc-log-overflowed: 82 83 ``allocationsLogOverflowed`` 84 85 Returns ``true`` if there have been more than [``maxAllocationsLogLength``][#max-alloc-log] allocations since the last time [``drainAllocationsLog``][#drain-alloc-log] was called and some data has been lost. Returns ``false`` otherwise. 86 87 88 Debugger.Memory Handler Functions 89 ********************************* 90 91 Similar to :doc:`Debugger's handler functions <../index>`, ``Debugger.Memory`` inherits accessor properties that store handler functions for SpiderMonkey to call when given events occur in debuggee code. 92 93 Unlike ``Debugger``‘s hooks, ``Debugger.Memory``’s handlers’ return values are not significant, and are ignored. The handler functions receive the ``Debugger.Memory``’s owning ``Debugger`` instance as their ``this`` value. The owning ``Debugger``’s ``uncaughtExceptionHandler`` is still fired for errors thrown in ``Debugger.Memory`` hooks. 94 95 On a new ``Debugger.Memory`` instance, each of these properties is initially ``undefined``. Any value assigned to a debugging handler must be either a function or ``undefined``; otherwise a ``TypeError`` is thrown. 96 97 Handler functions run in the same thread in which the event occurred. They run in the compartment to which they belong, not in a debuggee compartment. 98 99 100 ``onGarbageCollection(statistics)`` 101 102 A garbage collection cycle spanning one or more debuggees has just been completed. 103 104 The *statistics* parameter is an object containing information about the GC cycle. It has the following properties: 105 106 107 ``collections`` 108 109 The ``collections`` property’s value is an array. Because SpiderMonkey’s collector is incremental, a full collection cycle may consist of multiple discrete collection slices with the JS mutator running interleaved. For each collection slice that occurred, there is an entry in the ``collections`` array with the following form: 110 111 .. code-block:: javascript 112 113 { 114 "startTimestamp": timestamp, 115 "endTimestamp": timestamp, 116 } 117 118 Here the *timestamp* values are timestamps of the GC slice’s start and end events. 119 120 ``reason`` 121 122 A very short string describing the reason why the collection was triggered. Known values include the following: 123 124 - “API” 125 - “EAGER_ALLOC_TRIGGER” 126 - “DESTROY_RUNTIME” 127 - “LAST_DITCH” 128 - “TOO_MUCH_MALLOC” 129 - “ALLOC_TRIGGER” 130 - “DEBUG_GC” 131 - “COMPARTMENT_REVIVED” 132 - “RESET” 133 - “OUT_OF_NURSERY” 134 - “EVICT_NURSERY” 135 - “FULL_STORE_BUFFER” 136 - “SHARED_MEMORY_LIMIT” 137 - “PERIODIC_FULL_GC” 138 - “INCREMENTAL_TOO_SLOW” 139 - “DOM_WINDOW_UTILS” 140 - “COMPONENT_UTILS” 141 - “MEM_PRESSURE” 142 - “CC_WAITING” 143 - “CC_FORCED” 144 - “LOAD_END” 145 - “PAGE_HIDE” 146 - “NSJSCONTEXT_DESTROY” 147 - “SET_NEW_DOCUMENT” 148 - “SET_DOC_SHELL” 149 - “DOM_UTILS” 150 - “DOM_IPC” 151 - “DOM_WORKER” 152 - “INTER_SLICE_GC” 153 - “REFRESH_FRAME” 154 - “FULL_GC_TIMER” 155 - “SHUTDOWN_CC” 156 - “USER_INACTIVE” 157 158 159 ``nonincrementalReason`` 160 161 If SpiderMonkey’s collector determined it could not incrementally collect garbage, and had to do a full GC all at once, this is a short string describing the reason it determined the full GC was necessary. Otherwise, ``null`` is returned. Known values include the following: 162 163 - “GC mode” 164 - “malloc bytes trigger” 165 - “allocation trigger” 166 - “requested” 167 168 169 ``gcCycleNumber`` 170 171 The GC cycle’s “number”. Does not correspond to the number of GC cycles that have run, but is guaranteed to be monotonically increasing. 172 173 174 175 Function Properties of the ``Debugger.Memory.prototype`` Object 176 *************************************************************** 177 178 Memory Use Analysis Exposes Implementation Details 179 180 Memory analysis may yield surprising results, because browser implementation details that are transparent to content JavaScript often have visible effects on memory consumption. Web developers need to know their pages’ actual memory consumption on real browsers, so it is correct for the tool to expose these behaviors, as long as it is done in a way that helps developers make decisions about their own code. 181 182 This section covers some areas where Firefox’s actual behavior deviates from what one might expect from the specified behavior of the web platform. 183 184 Objects 185 ------- 186 187 SpiderMonkey objects usually use less memory than the naïve “table of properties with attributes” model would suggest. For example, it is typical for many objects to have identical sets of properties, with only the properties’ values varying from one object to the next. To take advantage of this regularity, SpiderMonkey objects with identical sets of properties may share their property metadata; only property values are stored directly in the object. 188 189 Array objects may also be optimized, if the set of live indices is dense. 190 191 192 Strings 193 ------- 194 195 SpiderMonkey has three representations of strings: 196 197 198 - Normal: the string’s text is counted in its size. 199 200 - Substring: the string is a substring of some other string, and points to that string for its storage. This representation may result in a small string retaining a very large string. However, the memory consumed by the string itself is a small constant independent of its size, since it is a reference to the larger string, a start position, and a length. 201 202 - Concatenations: When asked to concatenate two strings, SpiderMonkey may elect to delay copying the strings’ data, and represent the result as a pointer to the two original strings. Again, such a string retains other strings, but the memory consumed by the string itself is a small constant independent of its size, since it is a pair of pointers. 203 204 205 SpiderMonkey converts strings from the more complex representations to the simpler ones when it pleases. Such conversions usually increase memory consumption. 206 207 SpiderMonkey shares some strings amongst all web pages and browser JS. These shared strings, called *atoms*, are not included in censuses’ string counts. 208 209 210 Scripts 211 ------- 212 213 SpiderMonkey has a complex, hybrid representation of JavaScript code. There are four representations kept in memory: 214 215 216 - *Source code*. SpiderMonkey retains a copy of most JavaScript source code. 217 218 - *Compressed source code*. SpiderMonkey compresses JavaScript source code, and de-compresses it on demand. Heuristics determine how long to retain the uncompressed code. 219 220 - *Bytecode*. This is SpiderMonkey’s parsed representation of JavaScript. Bytecode can be interpreted directly, or used as input to a just-in-time compiler. Source is parsed into bytecode on demand; functions that are never called are never parsed. 221 222 - *Machine code*. SpiderMonkey includes several just-in-time compilers, each of which translates JavaScript source or bytecode to machine code. Heuristics determine which code to compile, and which compiler to use. Machine code may be dropped in response to memory pressure, and regenerated as needed. 223 224 225 Furthermore, SpiderMonkey tracks which types of values have appeared in variables and object properties. This type information can be large. 226 227 In a census, all the various forms of JavaScript code are placed in the ``"script"`` category. Type information is accounted to the ``"types"`` category. 228 229 230 Source Metadata 231 --------------- 232 233 Generated from file: 234 js/src/doc/Debugger/Debugger.Memory.md 235 236 Watermark: 237 sha256:2c1529d6932efec8c624a6f1f366b09cb7fce625a6468657fab81788240bc7ae 238 239 Changeset: 240 `e91b2c85aacd <https://hg.mozilla.org/mozilla-central/rev/e91b2c85aacd>`_