Debugger.Memory
The Debugger API
can help tools observe the debuggeeâs memory use in various ways:
-
It can mark each new object with the JavaScript call stack at which it was allocated.
-
It can log all object allocations, yielding a stream of JavaScript call stacks at which allocations have occurred.
-
It can compute a census of items belonging to the debuggee, categorizing items in various ways, and yielding item counts.
Ifdbg is a Debugger
instance, then the methods and accessor properties of dbg.memory
control howdbg observes its debuggeesâ memory use. The dbg.memory
object is an instance of Debugger.Memory
; its inherited accesors and methods are described below.
Allocation Site Tracking
The JavaScript engine marks each new object with the call stack at which it was allocated, if:
-
the object is allocated in the scope of a global object that is a debuggee of some
Debugger
instancedbg; and -
dbg.memory.trackingAllocationSites
is set totrue
. -
A Bernoulli trial succeeds, with probability equal to the maximum of
d.memory.allocationSamplingProbability
of allDebugger
instancesd
that are observing the global that this object is allocated within the scope of.
Given a Debugger.Object
instancedobj referring to some object, dobj.allocationSite
returns a saved call stack indicating wheredobjâs referent was allocated.
Allocation Logging
Ifdbg is a Debugger
instance, and dbg.memory.trackingAllocationSites
is set to true
, then the JavaScript engine logs each object allocated bydbgâ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 dbg.memory.maxAllocationsLogLength
.
Censuses
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. Ifdbg is a Debugger
instance, you can call dbg.memory.takeCensus
to conduct a census of its debuggeesâ possessions.
Accessor Properties of the Debugger.Memory.prototype
Object
Ifdbg is a Debugger
instance, then <i>dbg</i>.memory
is a Debugger.Memory
instance, which inherits the following accessor properties from its prototype:
trackingAllocationSites
-
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 producestrue
if the Debugger is capturing stacks for Object allocations, andfalse
otherwise. Allocation site tracking is initially disabled in a new Debugger.Assignment is fallible: if the Debugger cannot track allocation sites, it throws an
Error
instance.You can retrieve the allocation site for a given object with the
Debugger.Object.prototype.allocationSite
accessor property. allocationSamplingProbability
-
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â.
The default is 1, or logging every allocation.
Note that in the presence of multiple
Debugger
instances observing the same allocations within a globalâs scope, the maximumallocationSamplingProbability
of all theDebugger
s is used. maxAllocationsLogLength
- 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
. allocationsLogOverflowed
- 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. Returnsfalse
otherwise.
Debugger.Memory Handler Functions
Similar to Debugger
âs handler functions, Debugger.Memory
inherits accessor properties that store handler functions for SpiderMonkey to call when given events occur in debuggee code.
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.
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.
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.
onGarbageCollection(statistics)
-
A garbage collection cycle spanning one or more debuggees has just been completed.
The statistics parameter is an object containing information about the GC cycle. It has the following properties:
collections
-
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 thecollections
array with the following form:{ "startTimestamp":timestamp, "endTimestamp":timestamp, }
Here the timestamp values are timestamps of the GC sliceâs start and end events.
reason
-
A very short string describing the reason why the collection was triggered. Known values include the following:
- âAPIâ
- âEAGER_ALLOC_TRIGGERâ
- âDESTROY_RUNTIMEâ
- âLAST_DITCHâ
- âTOO_MUCH_MALLOCâ
- âALLOC_TRIGGERâ
- âDEBUG_GCâ
- âCOMPARTMENT_REVIVEDâ
- âRESETâ
- âOUT_OF_NURSERYâ
- âEVICT_NURSERYâ
- âFULL_STORE_BUFFERâ
- âSHARED_MEMORY_LIMITâ
- âPERIODIC_FULL_GCâ
- âINCREMENTAL_TOO_SLOWâ
- âDOM_WINDOW_UTILSâ
- âCOMPONENT_UTILSâ
- âMEM_PRESSUREâ
- âCC_WAITINGâ
- âCC_FORCEDâ
- âLOAD_ENDâ
- âPAGE_HIDEâ
- âNSJSCONTEXT_DESTROYâ
- âSET_NEW_DOCUMENTâ
- âSET_DOC_SHELLâ
- âDOM_UTILSâ
- âDOM_IPCâ
- âDOM_WORKERâ
- âINTER_SLICE_GCâ
- âREFRESH_FRAMEâ
- âFULL_GC_TIMERâ
- âSHUTDOWN_CCâ
- âUSER_INACTIVEâ
nonincrementalReason
-
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:- âGC modeâ
- âmalloc bytes triggerâ
- âallocation triggerâ
- ârequestedâ
gcCycleNumber
- The GC cycleâs ânumberâ. Does not correspond to the number of GC cycles that have run, but is guaranteed to be monotonically increasing.
Function Properties of the Debugger.Memory.prototype
Object
Memory Use Analysis Exposes Implementation Details
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.
This section covers some areas where Firefoxâs actual behavior deviates from what one might expect from the specified behavior of the web platform.
Objects
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.
Array objects may also be optimized, if the set of live indices is dense.
Strings
SpiderMonkey has three representations of strings:
-
Normal: the stringâs text is counted in its size.
-
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 simply a reference to the larger string, a start position, and a length.
-
Concatenations: When asked to concatenate two strings, SpiderMonkey may elect to delay copying the stringsâ data, and represent the result simply 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 simply a pair of pointers.
SpiderMonkey converts strings from the more complex representations to the simpler ones when it pleases. Such conversions usually increase memory consumption.
SpiderMonkey shares some strings amongst all web pages and browser JS. These shared strings, called atoms, are not included in censusesâ string counts.
Scripts
SpiderMonkey has a complex, hybrid representation of JavaScript code. There are four representations kept in memory:
-
Source code. SpiderMonkey retains a copy of most JavaScript source code.
-
Compressed source code. SpiderMonkey compresses JavaScript source code, and de-compresses it on demand. Heuristics determine how long to retain the uncompressed code.
-
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.
-
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.
Furthermore, SpiderMonkey tracks which types of values have appeared in variables and object properties. This type information can be large.
In a census, all the various forms of JavaScript code are placed in the "script"
category. Type information is accounted to the "types"
category.
Source Metadata
- Generated from file:
- js/src/doc/Debugger/Debugger.Memory.md
- Watermark:
- sha256:2c1529d6932efec8c624a6f1f366b09cb7fce625a6468657fab81788240bc7ae
- Changeset:
- e91b2c85aacd