summaryrefslogtreecommitdiffstats
path: root/js/src/doc/Debugger/Debugger.Script.md
diff options
context:
space:
mode:
authorMatt A. Tobin <mattatobin@localhost.localdomain>2018-02-02 04:16:08 -0500
committerMatt A. Tobin <mattatobin@localhost.localdomain>2018-02-02 04:16:08 -0500
commit5f8de423f190bbb79a62f804151bc24824fa32d8 (patch)
tree10027f336435511475e392454359edea8e25895d /js/src/doc/Debugger/Debugger.Script.md
parent49ee0794b5d912db1f95dce6eb52d781dc210db5 (diff)
downloadUXP-5f8de423f190bbb79a62f804151bc24824fa32d8.tar
UXP-5f8de423f190bbb79a62f804151bc24824fa32d8.tar.gz
UXP-5f8de423f190bbb79a62f804151bc24824fa32d8.tar.lz
UXP-5f8de423f190bbb79a62f804151bc24824fa32d8.tar.xz
UXP-5f8de423f190bbb79a62f804151bc24824fa32d8.zip
Add m-esr52 at 52.6.0
Diffstat (limited to 'js/src/doc/Debugger/Debugger.Script.md')
-rw-r--r--js/src/doc/Debugger/Debugger.Script.md379
1 files changed, 379 insertions, 0 deletions
diff --git a/js/src/doc/Debugger/Debugger.Script.md b/js/src/doc/Debugger/Debugger.Script.md
new file mode 100644
index 000000000..65eac9026
--- /dev/null
+++ b/js/src/doc/Debugger/Debugger.Script.md
@@ -0,0 +1,379 @@
+# Debugger.Script
+
+A `Debugger.Script` instance may refer to a sequence of bytecode in the
+debuggee or to a block of WebAssembly code. For the former, it is the
+[`Debugger`][debugger-object] API's presentation of a JSAPI `JSScript`
+object. The two cases are distinguished by their `format` property being
+`"js"` or `"wasm"`.
+
+## Debugger.Script for JSScripts
+
+For `Debugger.Script` instances referring to a `JSScript`, they are
+distinguished by their `format` property being `"js"`.
+
+Each of the following is represented by a single `JSScript` object:
+
+* The body of a function—that is, all the code in the function that is not
+ contained within some nested function.
+
+* The code passed to a single call to `eval`, excluding the bodies of any
+ functions that code defines.
+
+* The contents of a `<script>` element.
+
+* A DOM event handler, whether embedded in HTML or attached to the element
+ by other JavaScript code.
+
+* Code appearing in a `javascript:` URL.
+
+The [`Debugger`][debugger-object] interface constructs `Debugger.Script` objects as scripts
+of debuggee code are uncovered by the debugger: via the `onNewScript`
+handler method; via [`Debugger.Frame`][frame]'s `script` properties; via the
+`functionScript` method of [`Debugger.Object`][object] instances; and so on. For a
+given [`Debugger`][debugger-object] instance, SpiderMonkey constructs exactly one
+`Debugger.Script` instance for each underlying script object; debugger
+code can add its own properties to a script object and expect to find
+them later, use `==` to decide whether two expressions refer to the same
+script, and so on.
+
+(If more than one [`Debugger`][debugger-object] instance is debugging the same code, each
+[`Debugger`][debugger-object] gets a separate `Debugger.Script` instance for a given
+script. This allows the code using each [`Debugger`][debugger-object] instance to place
+whatever properties it likes on its `Debugger.Script` instances, without
+worrying about interfering with other debuggers.)
+
+A `Debugger.Script` instance is a strong reference to a JSScript object;
+it protects the script it refers to from being garbage collected.
+
+Note that SpiderMonkey may use the same `Debugger.Script` instances for
+equivalent functions or evaluated code—that is, scripts representing the
+same source code, at the same position in the same source file,
+evaluated in the same lexical environment.
+
+## Debugger.Script for WebAssembly
+
+For `Debugger.Script` instances referring to a block of WebAssembly code, they
+are distinguished by their `format` property being `"wasm"`.
+
+Currently only entire modules evaluated via `new WebAssembly.Module` are
+represented.
+
+`Debugger.Script` objects for WebAssembly are uncovered via `onNewScript` when
+a new WebAssembly module is instantiated and via the `findScripts` method on
+[`Debugger`][debugger-object] instances. SpiderMonkey constructs exactly one
+`Debugger.Script` for each underlying WebAssembly module per
+[`Debugger`][debugger-object] instance.
+
+A `Debugger.Script` instance is a strong reference to the underlying
+WebAssembly module; it protects the module it refers to from being garbage
+collected.
+
+Please note at the time of this writing, support for WebAssembly is
+very preliminary. Many properties and methods below throw.
+
+## Convention
+
+For descriptions of properties and methods below, if the behavior of the
+property or method differs between the instance referring to a `JSScript` or
+to a block of WebAssembly code, the text will be split into two sections,
+headed by "**if the instance refers to a `JSScript`**" and "**if the instance
+refers to WebAssembly code**", respectively. If the behavior does not differ,
+no such emphasized headings will appear.
+
+## Accessor Properties of the Debugger.Script Prototype Object
+
+A `Debugger.Script` instance inherits the following accessor properties
+from its prototype:
+
+`displayName`
+: **If the instance refers to a `JSScript`**, this is the script's display
+ name, if it has one. If the script has no display name &mdash; for example,
+ if it is a top-level `eval` script &mdash; this is `undefined`.
+
+ If the script's function has a given name, its display name is the same as
+ its function's given name.
+
+ If the script's function has no name, SpiderMonkey attempts to infer an
+ appropriate name for it given its context. For example:
+
+ ```language-js
+ function f() {} // display name: f (the given name)
+ var g = function () {}; // display name: g
+ o.p = function () {}; // display name: o.p
+ var q = {
+ r: function () {} // display name: q.r
+ };
+ ```
+
+ Note that the display name may not be a proper JavaScript identifier,
+ or even a proper expression: we attempt to find helpful names even when
+ the function is not immediately assigned as the value of some variable
+ or property. Thus, we use <code><i>a</i>/<i>b</i></code> to refer to
+ the <i>b</i> defined within <i>a</i>, and <code><i>a</i>&lt;</code> to
+ refer to a function that occurs somewhere within an expression that is
+ assigned to <i>a</i>. For example:
+
+ ```language-js
+ function h() {
+ var i = function() {}; // display name: h/i
+ f(function () {}); // display name: h/<
+ }
+ var s = f(function () {}); // display name: s<
+ ```
+
+ **If the instance refers to WebAssembly code**, throw a `TypeError`.
+
+`url`
+: **If the instance refers to a `JSScript`**, the filename or URL from which
+ this script's code was loaded. If the `source` property is non-`null`,
+ then this is equal to `source.url`.
+
+ **If the instance refers to WebAssembly code**, throw a `TypeError`.
+
+`startLine`
+: **If the instance refers to a `JSScript`**, the number of the line at
+ which this script's code starts, within the file or document named by
+ `url`.
+
+ **If the instance refers to WebAssembly code**, throw a `TypeError`.
+
+`lineCount`
+: **If the instance refers to a `JSScript`**, the number of lines this
+ script's code occupies, within the file or document named by `url`.
+
+ **If the instance refers to WebAssembly code**, throw a `TypeError`.
+
+`source`
+: **If the instance refers to a `JSScript`**, the
+ [`Debugger.Source`][source] instance representing the source code from
+ which this script was produced. This is `null` if the source code was not
+ retained.
+
+ **If the instance refers to WebAssembly code**, the
+ [`Debugger.Source`][source] instance representing the serialized text
+ format of the WebAssembly code.
+
+`sourceStart`
+: **If the instance refers to a `JSScript`**, the character within the
+ [`Debugger.Source`][source] instance given by `source` at which this
+ script's code starts; zero-based. If this is a function's script, this is
+ the index of the start of the `function` token in the source code.
+
+ **If the instance refers to WebAssembly code**, throw a `TypeError`.
+
+`sourceLength`
+: **If the instance refers to a `JSScript`**, the length, in characters, of
+ this script's code within the [`Debugger.Source`][source] instance given
+ by `source`.
+
+ **If the instance refers to WebAssembly code**, throw a `TypeError`.
+
+`global`
+: **If the instance refers to a `JSScript`**, a [`Debugger.Object`][object]
+ instance referring to the global object in whose scope this script
+ runs. The result refers to the global directly, not via a wrapper or a
+ `WindowProxy` ("outer window", in Firefox).
+
+ **If the instance refers to WebAssembly code**, throw a `TypeError`.
+
+`format`
+: **If the instance refers to a `JSScript`**, `"js"`.
+
+ **If the instance refers to WebAssembly code**, `"wasm"`.
+
+## Function Properties of the Debugger.Script Prototype Object
+
+The functions described below may only be called with a `this` value
+referring to a `Debugger.Script` instance; they may not be used as
+methods of other kinds of objects.
+
+`getAllOffsets()`
+: **If the instance refers to a `JSScript`**, return an array <i>L</i>
+ describing the relationship between bytecode instruction offsets and
+ source code positions in this script. <i>L</i> is sparse, and indexed by
+ source line number. If a source line number <i>line</i> has no code, then
+ <i>L</i> has no <i>line</i> property. If there is code for <i>line</i>,
+ then <code><i>L</i>[<i>line</i>]</code> is an array of offsets of byte
+ code instructions that are entry points to that line.
+
+ For example, suppose we have a script for the following source code:
+
+ ```language-js
+ a=[]
+ for (i=1; i < 10; i++)
+ // It's hip to be square.
+ a[i] = i*i;
+ ```
+
+ Calling `getAllOffsets()` on that code might yield an array like this:
+
+ ```language-js
+ [[0], [5, 20], , [10]]
+ ```
+
+ This array indicates that:
+
+ * the first line's code starts at offset 0 in the script;
+
+ * the `for` statement head has two entry points at offsets 5 and 20 (for
+ the initialization, which is performed only once, and the loop test,
+ which is performed at the start of each iteration);
+
+ * the third line has no code;
+
+ * and the fourth line begins at offset 10.
+
+ **If the instance refers to WebAssembly code**, throw a `TypeError`.
+
+`getAllColumnOffsets()`:
+: **If the instance refers to a `JSScript`**, return an array describing the
+ relationship between bytecode instruction offsets and source code
+ positions in this script. Unlike getAllOffsets(), which returns all
+ offsets that are entry points for each line, getAllColumnOffsets() returns
+ all offsets that are entry points for each (line, column) pair.
+
+ The elements of the array are objects, each of which describes a single
+ entry point, and contains the following properties:
+
+ * lineNumber: the line number for which offset is an entry point
+
+ * columnNumber: the column number for which offset is an entry point
+
+ * offset: the bytecode instruction offset of the entry point
+
+ For example, suppose we have a script for the following source code:
+
+ ```language-js
+ a=[]
+ for (i=1; i < 10; i++)
+ // It's hip to be square.
+ a[i] = i*i;
+ ```
+
+ Calling `getAllColumnOffsets()` on that code might yield an array like this:
+
+ ```language-js
+ [{ lineNumber: 0, columnNumber: 0, offset: 0 },
+ { lineNumber: 1, columnNumber: 5, offset: 5 },
+ { lineNumber: 1, columnNumber: 10, offset: 20 },
+ { lineNumber: 3, columnNumber: 4, offset: 10 }]
+ ```
+
+ **If the instance refers to WebAssembly code**, throw a `TypeError`.
+
+<code>getLineOffsets(<i>line</i>)</code>
+: **If the instance refers to a `JSScript`**, return an array of bytecode
+ instruction offsets representing the entry points to source line
+ <i>line</i>. If the script contains no executable code at that line, the
+ array returned is empty.
+
+ **If the instance refers to WebAssembly code**, throw a `TypeError`.
+
+<code>getOffsetLocation(<i>offset</i>)</code>
+: **If the instance refers to a `JSScript`**, return an object describing the
+ source code location responsible for the bytecode at <i>offset</i> in this
+ script. The object has the following properties:
+
+ * lineNumber: the line number for which offset is an entry point
+
+ * columnNumber: the column number for which offset is an entry point
+
+ * isEntryPoint: true if the offset is a column entry point, as
+ would be reported by getAllColumnOffsets(); otherwise false.
+
+ **If the instance refers to WebAssembly code**, throw a `TypeError`.
+
+`getOffsetsCoverage()`:
+: **If the instance refers to a `JSScript`**, return `null` or an array which
+ contains informations about the coverage of all opcodes. The elements of
+ the array are objects, each of which describes a single opcode, and
+ contains the following properties:
+
+ * lineNumber: the line number of the current opcode.
+
+ * columnNumber: the column number of the current opcode.
+
+ * offset: the bytecode instruction offset of the current opcode.
+
+ * count: the number of times the current opcode got executed.
+
+ If this script has no coverage, or if it is not instrumented, then this
+ function will return `null`. To ensure that the debuggee is instrumented,
+ the flag `Debugger.collectCoverageInfo` should be set to `true`.
+
+ **If the instance refers to WebAssembly code**, throw a `TypeError`.
+
+`getChildScripts()`
+: **If the instance refers to a `JSScript`**, return a new array whose
+ elements are Debugger.Script objects for each function
+ in this script. Only direct children are included; nested
+ children can be reached by walking the tree.
+
+ **If the instance refers to WebAssembly code**, throw a `TypeError`.
+
+<code>setBreakpoint(<i>offset</i>, <i>handler</i>)</code>
+: **If the instance refers to a `JSScript`**, set a breakpoint at the
+ bytecode instruction at <i>offset</i> in this script, reporting hits to
+ the `hit` method of <i>handler</i>. If <i>offset</i> is not a valid offset
+ in this script, throw an error.
+
+ When execution reaches the given instruction, SpiderMonkey calls the
+ `hit` method of <i>handler</i>, passing a [`Debugger.Frame`][frame]
+ instance representing the currently executing stack frame. The `hit`
+ method's return value should be a [resumption value][rv], determining
+ how execution should continue.
+
+ Any number of breakpoints may be set at a single location; when control
+ reaches that point, SpiderMonkey calls their handlers in an unspecified
+ order.
+
+ Any number of breakpoints may use the same <i>handler</i> object.
+
+ Breakpoint handler method calls are cross-compartment, intra-thread
+ calls: the call takes place in the same thread that hit the breakpoint,
+ and in the compartment containing the handler function (typically the
+ debugger's compartment).
+
+ The new breakpoint belongs to the [`Debugger`][debugger-object] instance to
+ which this script belongs. Disabling the [`Debugger`][debugger-object]
+ instance disables this breakpoint; and removing a global from the
+ [`Debugger`][debugger-object] instance's set of debuggees clears all the
+ breakpoints belonging to that [`Debugger`][debugger-object] instance in that
+ global's scripts.
+
+ **If the instance refers to WebAssembly code**, throw a `TypeError`.
+
+<code>getBreakpoints([<i>offset</i>])</code>
+: **If the instance refers to a `JSScript`**, return an array containing the
+ handler objects for all the breakpoints set at <i>offset</i> in this
+ script. If <i>offset</i> is omitted, return the handlers of all
+ breakpoints set anywhere in this script. If <i>offset</i> is present, but
+ not a valid offset in this script, throw an error.
+
+ **If the instance refers to WebAssembly code**, throw a `TypeError`.
+
+<code>clearBreakpoints(handler, [<i>offset</i>])</code>
+: **If the instance refers to a `JSScript`**, remove all breakpoints set in
+ this [`Debugger`][debugger-object] instance that use <i>handler</i> as
+ their handler. If <i>offset</i> is given, remove only those breakpoints
+ set at <i>offset</i> that use <i>handler</i>; if <i>offset</i> is not a
+ valid offset in this script, throw an error.
+
+ Note that, if breakpoints using other handler objects are set at the
+ same location(s) as <i>handler</i>, they remain in place.
+
+ **If the instance refers to WebAssembly code**, throw a `TypeError`.
+
+<code>clearAllBreakpoints([<i>offset</i>])</code>
+: **If the instance refers to a `JSScript`**, remove all breakpoints set in
+ this script. If <i>offset</i> is present, remove all breakpoints set at
+ that offset in this script; if <i>offset</i> is not a valid bytecode
+ offset in this script, throw an error.
+
+ **If the instance refers to WebAssembly code**, throw a `TypeError`.
+
+<code>isInCatchScope([<i>offset</i>])</code>
+: **If the instance refers to a `JSScript`**, this is `true` if this offset
+ falls within the scope of a try block, and `false` otherwise.
+
+ **If the instance refers to WebAssembly code**, throw a `TypeError`.