Debugger

This draft is being discussed in bug 636907.

The Debug object provides functions for debugging code running in a separate compartment. You can provide functions for SpiderMonkey to call when events like steps, calls, and breakpoint hits occur in the debuggee, examine the debuggee's stack frames, and inspect and manipulate the debuggee's objects.

Debug object event hook functions run in the same thread as the debuggee, on the same stack: when the event occurs, the debuggee pauses while your hook functions run, and resumes (unless you say otherwise) when your functions return.

The debugger and debuggee must be in separate compartments. Your hook functions run in the debugger's compartment. SpiderMonkey mediates their access to the debuggee's objects, and prevents the debuggee from accessing the debugger's objects at all.

The Debug object provides objects representing the debuggee's stack frames, scripts, and other internal interpreter structures, for your hook functions to examine and manipulate.

Debugger access to debuggee values

The Debug object follows certain conventions to help debuggers safely inspect and modify the debuggee's objects and values. Primitive values are passed freely between debugger and debuggee; copying or wrapping is handled transparently, as appropriate. Objects (including host objects like DOM nodes) received from the debuggee are fronted in the debugger by Debug.Object instances (described in detail below), which provide reflection-oriented methods for inspecting the referent object's properties and other characteristics. Of the debugger's objects, only Debug.Object instances may be passed to the debuggee: when this occurs, the debuggee receives the Debug.Object's referent, not the Debug.Object instance itself.

In the descriptions below, the term "debuggee value" means either a primitive value or a Debug.Object instance; it is a value that might be received from the debuggee, or that could be passed to the debuggee.

Beginning to Debug

To begin debugging another compartment's code, you create a Debug object for the debuggee compartment, and install your hook functions.

Debug(object)

Create a debugger object debugging object's compartment. Object is typically a global object, but can be any JavaScript object from the debuggee's compartment. The object must be in a different compartment than the calling code, and debugger/debuggee compartments may not form a cycle. Object's compartment must not be in use by another thread while this call runs.

Instances of Debug have the following methods:

setHooks(hooks)

Use the functions in hooks to handle events occurring in this debuggee. Hooks should be an object; each property should be named after a debugging event, and its value should be a function SpiderMonkey should call when the named event occurs. See below for descriptions of specific debugging hooks. This removes all previously registered hooks; after the call, only the hooks mentioned in hooks are in force. Thus, a call like setHooks({}) removes all debugging hooks. Hook function calls are cross-compartment, same-thread calls. Hook functions run in the thread in which the event occurred, not in the thread that registered the hooks. (It is your responsibility to ensure that two threads don't try to run in the same compartment). Hook functions run in the compartment to which they belong, not in the debuggee's compartment.

getHooks()

Return an object holding all the event hooks currently in force. The returned object is suitable for use with setHooks.

Debugging hooks

For each debugging hook, we give the name of the hook and the arguments passed to its handler function, and describe the circumstances under which SpiderMonkey calls it.

interrupt(frame)

A bytecode instruction is about to execute in the stack frame represented by frame, a Debug.Frame instance. Naturally, frame is the youngest debuggee frame. This hook function's return value determines how execution should continue:

• If it returns true, execution continues normally.
• If it returns an object of the form { throw: value }, then value is thrown as an exception from the current bytecode instruction. value must be a debuggee value.
• If it returns an object of the form { return: value }, then value is immediately returned as the current value of the function. value must be a debuggee value.
• If it returns null, the calling code is terminated, as if it had been cancelled by the "slow script" dialog box.
• If the hook throws an exception, ... well, we're in trouble. That's an error in the debugger which should be reported somehow, but certainly not handled by the debuggee.

newScript(script, [function])

New code, represented by the Debug.Script instance script, has been loaded into the debuggee's compartment. If the new code is part of a function, function is a Debug.Object reference to the function object. (Not all code is part of a function; for example, the code appearing in a <script> tag that is outside of any functions defined in that tag would be passed to newScript without an accompanying function argument.) Note that script may be a temporary script, created for a call to eval and destroyed when its execution is complete.

destroyScript(script)

SpiderMonkey has determined that script will no longer be needed, and is about to throw it away. The garbage collector may have found that the script is no longer in use, or perhaps eval has finished executing the script, and is about to destroy it. In any case, operations on script after this hook function returns will throw an error.

debuggerHandler(frame)

The debuggee has executed a debugger statement in frame. This hook function's return value determines how execution proceeds, as for the interrupt hook function.

sourceHandler(ASuffusionOfYellow)

This hook function is never called. If it is ever called, a contradiction has been proven, and the debugger is free to assume that everything is true.

enterFrame(frame, call)

The stack frame frame is about to begin executing code. (Naturally, frame is currently the youngest debuggee frame.) If call is true, it is a function call; if call is false, it is global or eval code. If this hook function returns a function f, SpiderMonkey will call f when execution of frame completes, passing one argument indicating how it completed.

• If the argument is of the form { return: value }, then the code completed normally, yielding value. Value is a debuggee value.
• If the argument is of the form { throw: value }, then the code threw value as an exception. Value is a debuggee value.
• If the argument is null, then the code was terminated, as if by the "slow script" dialog box.

throw(frame, value)

The code running in frame is about to throw value as an exception. The value this hook function returns determines how execution proceeds, as for interrupt.

error(frame, report)

SpiderMonkey is about to report an error in frame. Report is an object describing the error, with the following properties:

message

The fully formatted error message.

file

If present, the source file name, URL, etc. (If this property is present, the line property will be too, and vice versa.)

line

If present, the source line number at which the error occurred.

lineText

If present, this is the source code of the offending line.

offset

The index of the character within lineText at which the error occurred.

warning

Present and true if this is a warning; absent otherwise.

strict

Present and true if this error or warning is due to the strict option (not to be confused with ES strict mode)

exception

Present and true if an exception will be thrown; absent otherwise.

arguments

An array of strings, representing the arguments substituted into the error message.

Debug.Frame

A Debug.Frame instance represents a debuggee stack frame. Given a Debug.Frame instance, you can find the script the frame is executing, walk the stack to older frames, find the lexical environment in which the execution is taking place, and so on.

SpiderMonkey creates instances of Debug.Frame as needed in two situations: when it calls a hook function that expects a frame as an argument, and when the debugger reads an existing frame's older property. SpiderMonkey creates only one Debug.Frame instance for a given debuggee frame; every hook function called while the debuggee is running in a given frame receives the same frame object; and walking the stack back to a previously accessed frame yields the same frame object as before. Debugger code can add its own properties to a frame object and expect to find them later, use == to decide whether two expressions refer to the same frame, and so on.

A Debug.Frame instance is a weak reference to the frame; once the debuggee destroys the frame (perhaps by returning from the function or completing the eval call), the Debug.Frame instance becomes inactive: its properties become undefined, and calls to its methods will throw an exception.

A Debug.Frame instance has the following properties, which are all non-writable and non-configurable:

type

A string describing what sort of frame this is:

• "call": a frame running a function call.
• "eval": a frame running code passed to eval.
• "global": a frame running global code (JavaScript that is neither of the above)
• "host": a frame for a call to a host function (I'm not sure if we can obtain these)
• "debugger": a frame for a call to user code invoked by the debugger (see the eval method below)
• "dummy": a frame pushed for stupid people (rather—I don't know what this is)

older

The next-older frame, in which control will resume when this frame completes.

depth

The depth of this frame, counting from oldest to youngest; the oldest frame has a depth of zero.

callee

The function whose application created this frame. Present only on "call" and "host" frames.

generator

True if this frame is a generator frame, false otherwise. Present only on frames whose type is "call".

constructing

True if this frame is for a function called as a constructor, false otherwise. Present on "call" and "host" frames.

script

The script being executed in this frame (a Debug.Script instance). Present on "call", "eval", and "global" frames. On "call" frames, this is equal to callee.script.

offset

The offset of the bytecode instruction currently being executed in script. Present when script is.

environment

The lexical environment within which evaluation is taking place (a Debug.Object instance). Present on "call", "eval", and "global" frames.

this

The value of this for the current frame (a debuggee value). Present on "call", "eval", and "host" frames.

arguments

The arguments passed to the current frame, as an array of debuggee values. (The array itself is an ordinary array in the debugger compartment.) Present on "call", "eval", and "host" frames.

A Debug.Frame instance has the following methods:

eval(code)

Begin evaluating code in the scope of this frame. Code is a string. This pushes a "debugger" frame on the debuggee's stack, evaluates code with all extant hook functions active, and returns a value of the sort passed to an enterFrame completion function describing how the code completed. Note that, although this method mixes the debugger's own stack frames with the debuggee's, walking the stack only shows the debuggee's frames; the continuation of the debugger's call to this method, up to the debugging hook function call, is represented by a single "debugger" frame. The next younger frame is an "eval" frame running code itself.

finish(result) (future plan)

Pop this frame (and any younger frames) from the stack as if this frame had completed. Result is a value of the sort that the interrupt hook might return, indicating how execution should be prepared to continue. Note that this does not resume the debuggee's execution; it merely adjusts the debuggee's state to what it would be if this frame's execution had completed. You must return true from the hook function to resume execution in that state. This cannot remove any "host" frames (calls through C++) from the stack. (We might be able to make this work eventually, but it will take some cleverness.)

restart(function, this, arguments) (future plan)

Pop any younger frames from the stack, and then change this frame into a frame for a call to function, with the given this value and arguments. This should be a debuggee value, or { asConstructor: true } to invoke function as a constructor, in which case SpiderMonkey provides an appropriate this value itself. Arguments should be an array of debuggee values. This frame must be a "call" frame. This can be used as a primitive in implementing some forms of a "patch and continue" debugger feature. Note that this does not resume the debuggee's execution; it merely adjusts the debuggee's state to what it would be if this frame were about to make this call. You must return true from the hook function to resume execution in that state. Like finish, this cannot remove "host" frames from the stack.

Generator Frames

SpiderMonkey supports generator-iterator objects, which produce a series of values by repeatedly suspending the execution of a function or expression. For example, calling a function that uses yield produces a generator-iterator object, as does evaluating a generator expression like (i*i for each (i in [1,2,3])).

A generator-iterator object refers to a stack frame with no fixed continuation frame. While the generator's code is running, its continuation is whatever frame called its next method; while the generator is suspended, it has no particular continuation frame; and when it resumes again, the continuation frame for that resumption could be different from that of the previous resumption.

When you use the Debug object to inspect a program that is running a generator frame, that frame appears on the stack like any other call frame, except that its generator property is true. Such a frame will disappear from the stack when it is suspended, and reappear (possibly with a different older frame and depth value) each time it is resumed.

Debug.Script

weak reference

Debug.Object

A Debug.Object instance represents an object in the debuggee. Debugger code never accesses debuggee objects directly; instead, it operates on Debug.Object instances that refer to the debuggee objects. SpiderMonkey's compartment system ensures that this separation is respected.

A Debug.Object instance has reflection-oriented methods to inspect and modify its referent. The referent's properties do not appear directly as properties of the Debug.Object instance; the debugger can access them only through methods like Debug.Object.prototype.getOwnPropertyDescriptor and Debug.Object.prototype.defineProperty, ensuring that the debugger will not inadvertently invoke the referent's getters and setters.

SpiderMonkey creates exactly one Debug.Object instance for each debuggee object it presents to the debugger: if the debugger encounters the same object through two different routes (perhaps two functions are called on the same object), SpiderMonkey presents the same Debug.Object instance to the debugger each time. This means that the debugger can use the == operator to recognize when two Debug.Object instances refer to the same debuggee object, and place its own properties on a Debug.Object instance to store metadata about particular debuggee objects.

While most Debug.Object instances are created by SpiderMonkey in the process of exposing debuggee's behavior and state to the debugger, the debugger can apply the Debug.Object constructor to its own objects, to copy them into the debuggee; see the description of the Debug.Object constructor below.

Debug.Object instances protect their referents from the garbage collector; as long as the Debug.Object instance is live, the referent remains live. Garbage collection has no debugger-visible effect.

The Debug.Object constructor

When called via a new expression, the Debug.Object constructor takes one argument, an object in the debugger's compartment, and applies the HTML5 "structured cloning" algorithm to copy the object into the debuggee's compartment. It then returns a Debug.Object instance referring to the copy. It is an error to apply Debug.Object to a primitive value via a new expression.

When applied as a function, Debug.Object behaves as above, except that primitive values are returned unchanged (although possibly wrapped, in an ordinary cross-compartment wrapper). This allows the debugger to use Debug.Object as a generic "debugger value to debuggee value" conversion function.

Properties of the Debug.Object constructor

create(prototype, [properties])

Create a new object in the debuggee's compartment, and return a Debug.Object referring to it. The new object's prototype is prototype; prototype must be an object. The new object's properties are as given by properties, as if it were passed to the standard Object.defineProperties function.

Properties of the Debug.Object prototype

getPrototype()

Return the prototype of this Debug.Object's referent (as a new Debug.Object instance), or null if it has no prototype.

getOwnPropertyDescriptor(name)

Return a property descriptor for the property named name of the object this Debug.Object instance refers to. (This function behaves like the standard Object.getOwnPropertyDescriptor function, except that the object being inspected is implicit; the property descriptor returned is in the debugger's compartment; and its value, get, and set properties, if present, are debuggee values.)

getOwnPropertyNames()

Return an array of strings naming all the own properties of this Debug.Object's referent, as if Object.getOwnPropertyNames(referent) had been called in the debuggee, and the result copied to the debugger's compartment.

defineProperty(name, attributes)

Define a property on this Debug.Object's referent named name, as described by the property descriptor descriptor. Any value, get, and set properties of attributes must be debuggee values. (This function behaves like Object.defineProperty, except that the target object is implicit, and in a different compartment from the function and descriptor.)

defineProperties(properties)

Define properties on this Debug.Object's referent, as given by properties. (This function behaves like Object.defineProperties, except that the target object is implicit, and in a different compartment from the properties argument.)

hasOwnProperty(name)

Return true if this Debug.Object's referent has an own property named name.

deleteProperty(name)

Remove the property named name from this Debug.Object's referent. Return true if the property was successfully removed, or if the referent has no such property. Return false if the property is non-configurable.

seal()

Prevent properties from being added or deleted from this Debug.Object's referent. Return this Debug.Object instance. (This function behaves like the standard Object.seal function, except that the object to be sealed is implicit and in a different compartment from the caller.)

freeze()

Prevent properties from being added or deleted from this Debug.Object's referent, and mark each property as non-writable. Return this Debug.Object instance. (This function behaves like the standard Object.freeze function, except that the object to be sealed is implicit and in a different compartment from the caller.)

preventExtensions()

Prevent properties from being added to this Debug.Object's referent. (This function behaves like the standard Object.preventExtensions function, except that the object to operate on is implicit and in a different compartment from the caller.)

isSealed()

Return true if this Debug.Object's referent is sealed—that is, if it is not extensible, and all its properties have been marked as non-configurable. (This function behaves like the standard Object.isSealed function, except that the object inspected is implicit and in a different compartment from the caller.)

isFrozen()

Return true if this Debug.Object's referent is frozen—that is, if it is not extensible, and all its properties have been marked as non-configurable and read-only. (This function behaves like the standard Object.isFrozen function, except that the object inspected is implicit and in a different compartment from the caller.)

isExtensible()

Return true if this Debug.Object's referent is extensible—that is, if it can have new properties defined on it. (This function behaves like the standard Object.isExtensible function, except that the object inspected is implicit and in a different compartment from the caller.)

getClass()

Return a string naming the ECMAScript <code>[[Class]]</code> of this Debug.Object's referent.

referentToString()

Return a string representing this Debug.Object's referent, showing its class and any other useful information, without invoking its toString or toSource members, or running any other debuggee code. The specific string returned is unspecified. (It is better to add functions to Debug.Object.prototype that retrieve the information you need about the object than to depend on details of safeToString's behavior.) (Note that simply calling the toString method of a Debug.Object instance applies to instance itself, not its referent, and thus returns something like "[Object Debug.Object]".)