diff options
Diffstat (limited to 'js/src/doc/SavedFrame/SavedFrame.md')
-rw-r--r-- | js/src/doc/SavedFrame/SavedFrame.md | 88 |
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. |