Add m-esr52 at 52.6.0

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.