diff options
Diffstat (limited to 'js/src/doc/Debugger/Debugger.Script.md')
| -rw-r--r-- | js/src/doc/Debugger/Debugger.Script.md | 379 |
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 — for example, + if it is a top-level `eval` script — 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><</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`. |