diff options
author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-19 00:47:55 +0000 |
---|---|---|
committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-19 00:47:55 +0000 |
commit | 26a029d407be480d791972afb5975cf62c9360a6 (patch) | |
tree | f435a8308119effd964b339f76abb83a57c29483 /js/src/doc/SavedFrame/index.md | |
parent | Initial commit. (diff) | |
download | firefox-26a029d407be480d791972afb5975cf62c9360a6.tar.xz firefox-26a029d407be480d791972afb5975cf62c9360a6.zip |
Adding upstream version 124.0.1.upstream/124.0.1
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'js/src/doc/SavedFrame/index.md')
-rw-r--r-- | js/src/doc/SavedFrame/index.md | 95 |
1 files changed, 95 insertions, 0 deletions
diff --git a/js/src/doc/SavedFrame/index.md b/js/src/doc/SavedFrame/index.md new file mode 100644 index 0000000000..cdd4643a64 --- /dev/null +++ b/js/src/doc/SavedFrame/index.md @@ -0,0 +1,95 @@ +# 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. + +```text +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. + +### `sourceId` +The process-unique internal integer ID of this source. Usable to match up +a SavedFrame with a [Debugger.Source][dbg-source] using its `id` property. + +### `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. + +[dbg-source]: ../Debugger/Debugger.Source.md |