1# SavedFrame
2
3A `SavedFrame` instance is a singly linked list of stack frames. It represents a
4JavaScript call stack at a past moment of execution. Younger frames hold a
5reference to the frames that invoked them. The older tails are shared across
6many younger frames.
7
8`SavedFrame` stacks should generally be captured, allocated, and live within the
9compartment that is being observed or debugged. Usually this is a content
10compartment.
11
12## Capturing `SavedFrame` Stacks
13
14### From C++
15
16Use `JS::CaptureCurrentStack` declared in `jsapi.h`.
17
18### From JS
19
20Use `saveStack`, accessible via `Components.utils.getJSTestingFunction()`.
21
22## Including and Excluding Chrome Frames
23
24Consider the following `SavedFrame` stack. Arrows represent links from child to
25parent frame, `content.js` is from a compartment with content principals, and
26`chrome.js` is from a compartment with chrome principals.
27
28```text
29function A from content.js
30            |
31            V
32function B from chrome.js
33            |
34            V
35function C from content.js
36```
37The content compartment will ever have one view of this stack: `A -> C`.
38
39However, a chrome compartment has a choice: it can either take the same view
40that the content compartment has (`A -> C`), or it can view all stack frames,
41including the frames from chrome compartments (`A -> B -> C`). To view
42everything, use an `XrayWrapper`. This is the default wrapper. To see the stack
43as the content compartment sees it, waive the xray wrapper with
44`Components.utils.waiveXrays`:
45
46    const contentViewOfStack = Components.utils.waiveXrays(someStack);
47
48## Accessor Properties of the `SavedFrame.prototype` Object
49
50### `source`
51The source URL for this stack frame, as a string.
52
53### `sourceId`
54The process-unique internal integer ID of this source. Usable to match up
55a SavedFrame with a [Debugger.Source][dbg-source] using its `id` property.
56
57### `line`
58The line number for this stack frame.
59
60### `column`
61The column number for this stack frame.
62
63### `functionDisplayName`
64Either SpiderMonkey's inferred name for this stack frame's function, or
65    `null`.
66
67### `asyncCause`
68If this stack frame is the `asyncParent` of other stack frames, then this is
69a string representing the type of asynchronous call by which this frame
70invoked its children. For example, if this frame's children are calls to
71handlers for a promise this frame created, this frame's `asyncCause` would
72be `"Promise"`. If the asynchronous call was started in a descendant frame
73to which the requester of the property does not have access, this will be
74the generic string `"Async"`. If this is not an asynchronous call point,
75this will be `null`.
76
77### `asyncParent`
78If this stack frame was called as a result of an asynchronous operation, for
79example if the function referenced by this frame is a promise handler, this
80property points to the stack frame responsible for the asynchronous call,
81for example where the promise was created. If the frame responsible for the
82call is not accessible to the caller, this points to the youngest accessible
83ancestor of the real frame, if any. In all other cases, this is `null`.
84
85### `parent`
86This stack frame's caller, or `null` if this is the oldest frame on the
87stack. In this case, there might be an `asyncParent` instead.
88
89## Function Properties of the `SavedFrame.prototype` Object
90
91### `toString()`
92Return this frame and its parents formatted as a human readable stack trace
93string.
94
95[dbg-source]: ../Debugger/Debugger.Source.md
96