Confirmed users
497
edits
Debugger: Difference between revisions
→Debug.Script: Initial text.
(→Debug.Object: Add function access.) |
(→Debug.Script: Initial text.) |
||
| Line 198: | Line 198: | ||
== Debug.Script == | == Debug.Script == | ||
weak reference | A <code>Debug.Script</code> instance refers to a sequence of bytecode in the debuggee; it is the JavaScript-level presentation of a JSAPI <code>JSScript</code> object. Each of the following is represented by single JSScript object: | ||
<ul> | |||
<li>The body of a function—that is, all the code in the function that is not contained within some nested function. | |||
<li>The code passed to a single call to <code>eval</code>, excluding the bodies of any functions that code defines. | |||
<li>The contents of a <code><script></code> element. | |||
<li>A DOM event handler, whether embedded in HTML or attached to the element by other JavaScript code. | |||
<li>Code appearing in a <code>javascript:</code> URL. | |||
</ul> | |||
The Debug interface constructs <code>Debug.Script</code> objects as script objects are uncovered by the debugger: via the <code>newScript</code> hook; via <code>Debug.Frame</code>'s <code>script</code> properties; via the <code>functionScript</code> method of <code>Debug.Object</code> instances; and so on. It constructs exactly one <code>Debug.Script</code> instance for each underlying script object; debugger code can add its own properties to a script object and expect to find them later, use <code>==</code> to decide whether two expressions refer to the same script, and so on. | |||
A <code>Debug.Script</code> instance is a weak reference to a JSScript object; it does not protect the script it refers to from being freed or garbage collected. When SpiderMonkey decides to free the script, it calls the <code>destroyScript</code> debugger hook function to let the debugger know. Once that call has returned, the <code>Debug.Script</code> object is marked as no longer usable; and further operations on it will throw exceptions. | |||
The lifetime of a script depends on its origin. A function script is shared by all closures produced for that function, and lives as long as there are live closures referring to it. An <code>eval</code> script usually lives until the call to <code>eval</code> completes, but SpiderMonkey caches some scripts, making their lifetimes unpredictable. Debuggers should avoid depending on scripts' lifetimes once the stack frames, functions, and so on that own them have been destroyed. | |||
=== Properties of the Debug.Script prototype === | |||
The functions described below may only be called with a this value referring to a <code>Debug.Script</code> instance; they may not be used as methods of other kinds of objects. | |||
<dl> | |||
<dt>decompile([<i>pretty</i>]) | |||
<dd>Return a string containing JavaScript source code equivalent in its effect and result to this script. If <i>pretty</i> is present and true, produce indented code with line breaks. | |||
<dt>setBreakpoint(<i>offset</i>, <i>handler</i>) | |||
<dd>Set a breakpoint at the bytecode instruction at <i>offset</i> in this script. When execution reaches this point, SpiderMonkey calls the function <i>handler</i> in the debugger's compartment, passing no arguments. This replaces any existing trap at <i>offset</i> in this script. | |||
(While a typical design would have debugger objects that represent breakpoints and handler functions whose behavior is driven by those objects, it seems practical in JavaScript to have the handler function play both roles, since it is itself an object. Other code can access function objects' properties, and the function's own code can find them by referring to the its own name, as in <code>function f() { ... f.x ... }</code>.) | |||
<dt>clearBreakpoint(<i>offset</i>) | |||
<dd>Remove any breakpoint set at <i>offset</i> in this script. | |||
<dt>clearAllBreakpoints(<i>offset</i>) | |||
<dd>Remove all breakpoints set in this script. (See also the <code>Debug</code> object's <code>clearAllBreakpoints</code> method.) | |||
<dt>getOffsetsAndLines() | |||
<dd>Return an array of objects describing the relationship between bytecode instruction offsets and source code positions in this script. The array is ordered by bytecode offset, and includes an element for every offset that serves as an entry point for a line of source code. Each element is an object of the form <code>{ offset:<i>offset</i>, line:<i>line</i> }</code>, where <i>offset</i> is the offset of the bytecode instruction, and <i>line</i> is the source line number within the script's url corresponding to that bytecode instruction. | |||
(Note that lines containing some kinds of statements may have several entry points; for example, the head of a <code>for</code> loop may have separate entry points for when the loop is first entered and when an iteration completes.) | |||
<dt>getLineOffsets(<i>line</i>) | |||
<dd>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. | |||
<dt>getOffsetLine(<i>offset</i>) | |||
<dd>Return the source code line responsible for the bytecode at <i>offset</i> in this script. | |||
</dl> | |||
=== Properties of Debug.Script instances === | |||
<dl> | |||
<dt>url | |||
<dd>The filename or URL from which this script's code was loaded. | |||
<dt>startLine | |||
<dd>The number of the line at which this script's code starts, within the file or document named by <code>url</code>. | |||
<dt>length | |||
<dd>The number of lines this script's code occupies, within the file or document named by <code>url</code>. | |||
<dt>singleStepMode | |||
<dd>True if executing this script will produce calls to the <code>Debug</code> instance's <code>interrupt</code> hook for each source line. The debugger may assign boolean values to this property to enable and disable single stepping support for the script. | |||
</dl> | |||
== Debug.Object== | == Debug.Object== | ||