summaryrefslogtreecommitdiffstats
path: root/js/src/doc/SavedFrame/SavedFrame.md
diff options
context:
space:
mode:
Diffstat (limited to 'js/src/doc/SavedFrame/SavedFrame.md')
-rw-r--r--js/src/doc/SavedFrame/SavedFrame.md88
1 files changed, 88 insertions, 0 deletions
diff --git a/js/src/doc/SavedFrame/SavedFrame.md b/js/src/doc/SavedFrame/SavedFrame.md
new file mode 100644
index 000000000..7d06b445b
--- /dev/null
+++ b/js/src/doc/SavedFrame/SavedFrame.md
@@ -0,0 +1,88 @@
+# `SavedFrame`
+
+A `SavedFrame` instance is a singly linked list of stack frames. It represents a
+JavaScript call stack at a past moment of execution. Younger frames hold a
+reference to the frames that invoked them. The older tails are shared across
+many younger frames.
+
+`SavedFrame` stacks should generally be captured, allocated, and live within the
+compartment that is being observed or debugged. Usually this is a content
+compartment.
+
+## Capturing `SavedFrame` Stacks
+
+### From C++
+
+Use `JS::CaptureCurrentStack` declared in `jsapi.h`.
+
+### From JS
+
+Use `saveStack`, accessible via `Components.utils.getJSTestingFunction()`.
+
+## Including and Excluding Chrome Frames
+
+Consider the following `SavedFrame` stack. Arrows represent links from child to
+parent frame, `content.js` is from a compartment with content principals, and
+`chrome.js` is from a compartment with chrome principals.
+
+ function A from content.js
+ |
+ V
+ function B from chrome.js
+ |
+ V
+ function C from content.js
+
+The content compartment will ever have one view of this stack: `A -> C`.
+
+However, a chrome compartment has a choice: it can either take the same view
+that the content compartment has (`A -> C`), or it can view all stack frames,
+including the frames from chrome compartments (`A -> B -> C`). To view
+everything, use an `XrayWrapper`. This is the default wrapper. To see the stack
+as the content compartment sees it, waive the xray wrapper with
+`Components.utils.waiveXrays`:
+
+ const contentViewOfStack = Components.utils.waiveXrays(someStack);
+
+## Accessor Properties of the `SavedFrame.prototype` Object
+
+`source`
+: The source URL for this stack frame, as a string.
+
+`line`
+: The line number for this stack frame.
+
+`column`
+: The column number for this stack frame.
+
+`functionDisplayName`
+: Either SpiderMonkey's inferred name for this stack frame's function, or
+ `null`.
+
+`asyncCause`
+: If this stack frame is the `asyncParent` of other stack frames, then this is
+ a string representing the type of asynchronous call by which this frame
+ invoked its children. For example, if this frame's children are calls to
+ handlers for a promise this frame created, this frame's `asyncCause` would
+ be `"Promise"`. If the asynchronous call was started in a descendant frame
+ to which the requester of the property does not have access, this will be
+ the generic string `"Async"`. If this is not an asynchronous call point,
+ this will be `null`.
+
+`asyncParent`
+: If this stack frame was called as a result of an asynchronous operation, for
+ example if the function referenced by this frame is a promise handler, this
+ property points to the stack frame responsible for the asynchronous call,
+ for example where the promise was created. If the frame responsible for the
+ call is not accessible to the caller, this points to the youngest accessible
+ ancestor of the real frame, if any. In all other cases, this is `null`.
+
+`parent`
+: This stack frame's caller, or `null` if this is the oldest frame on the
+ stack. In this case, there might be an `asyncParent` instead.
+
+## Function Properties of the `SavedFrame.prototype` Object
+
+`toString`
+: Return this frame and its parents formatted as a human readable stack trace
+ string.