Remote Debugging Protocol: Difference between revisions

Each actor (other than the root) has a parent actor; closing communications with the parent closes communications with all its descendants. This establishes automatic limits on lifetimes for actor names, and allows the server to free associated storage, remove breakpoints, and so on. The root actor has no owner, and lives as long as the underlying connection to the client does. When the underlying connection is closed, all actor names are closed.

where <i>actor</i> is the actor to whom the packet is directed&mdash;actor names are always JSON integers&mdash;and <i>type</i> is a string specifying what sort of packet it is. Additional properties may be present, depending on <i>type</i>.

The root actor's name is always zero. <i>app-type</i> is a JSON string indicating what sort of program the server represents. There may be more properties present, depending on <i>app-type</i>.

<i>traits</i> is a JSON object describing protocol variants this server supports that are not convenient for the client to detect otherwise. The property names present indicate what traits the server has; the properties' values depend on their names. This version of the protocol defines no traits, so <i>traits</i> must be a JSON object with no properties, {}.

To get a list of the top-level browsing contexts present in a browser, a client should send a packet like the following to the root actor:

The response should have the form:

   { "from":0, "contexts":[<i>context</i>...] }

The <tt>contexts</tt> property is a list with one element for each top-level browsing context present in the browser. Each <i>context</i> has the following form:

Actors representing independent threads of JavaScript execution, like browsing contexts and web workers, are collectively known as "threads". Interactions with actors representing threads follow a more complication communication pattern.

* <b>Detached</b>: the thread is running freely, and not presently interacting with the debugger. Detached threads run, encounter errors, and exit without exchanging any sort of messages with the debugger. A debugger can attach to a thread, putting it in the "Running" state. Or, a detached thread may exit on its own, entering the "Exited" state.

* <b>Running</b>: the thread is running under the debugger's observation, executing JavaScript code or possibly blocked waiting for input. It will report exceptions, breakpoint hits, watchpoint hits, and other interesting events to the client, and enter the "paused" state. The debugger can also interrupt a running thread; this elicits a response and puts the thread in the "paused" state. A running thread may also exit, entering the "exited" state.

* <b>Paused</b>: the thread has reported a pause to the client and is awaiting further instructions. In this state, a thread can accept requests and send replies. If the client asks the thread to continue or step, it returns to the "running" state.

* In states where a transition can be initiated by either the debugger or the thread, it is always clear to the debugger which state the thread actually entered, and for what reason.<p>For example, if the debugger interrupts a running thread, it cannot be sure whether the thread stopped because of the interruption, paused of its own accord (to report a watchpoint hit, say), or exited. However, the next packet the debugger receives will either be "interrupted", "paused", or "exited", resolving the ambiguity.</p><p>Similarly, when the debugger attaches to a thread, it cannot be sure whether it has succeeded in attaching to the thread, or whether the thread exited before the attachment request arrived. However, in either case the debugger can expect a disambiguating response: if the attach suceeded, it receives an "attached" packet; and in the second case, it receives an "exit" packet.</p><p>To support this property, the thread ignores certain debugger packets in some states (the "interrupt" packet in the "Paused" and "Exited" states, for exmple). These cases all handle situations where the ignored packet was preempted by some thread action.</p>

   { "to":<i>thread</i>, "type":"attach", "pause-for":<i>events</i> }

This tells the thread to continue to run, but asks it to pause if any of

the event described by <i>events</i> occurs. The form of <i>events</i> is

described in [[#Events]].

This indicates that the thread received the <tt>attach</tt> packet, and

will continue to run, reporting events of interest to the debugger. The

thread is now in the <b>Running</b> state. The actor name <i>thread</i> remains

valid until the client detaches from the thread or acknowledges a thread

exit.

This indicates that the thread exited before receiving the <tt>attach</tt>

packet. The thread is now in the <b>Exited</b> state. The client must

respond to this with a <tt>release</tt> packet; see [[#Exiting_Threads|Exiting Threads]].

This indicates that the client has detached from the thread. The thread is

now in the <b>Detached</b> state: it can run freely, and no longer reports

events to the client. The actor name <i>thread</i> is released and

available for reuse.

This series of packets indicates that the thread paused of its own accord

(for the reason given by the additional properties of the "paused" packet),

and only then received the "detach" packet. As above, this indicates that

the thread is in the <b>Detached</b> state, and the actor name is available

for reuse.

This indicates that the thread exited on its own before receiving the

"detach" packet. The client should follow by sending a "release" packet; see [[#Exiting_Threads|Exiting Threads]], below.

Once the client has attached to a thread, it is in the <b>Running</b>

state. In this state, four things can happen:

Note that a client action can occur simultaneously with a thread action.

The protocol is designed to avoid ambiguities when both client and thread

act simultaneously.

If the thread pauses to report an interesting event to the client, it sends

a packet of the form:

   { "from":<i>thread</i>, "type":"paused", "frame":<i>frame</i>, "reason":<i>reason</i> }

This indicates that the thread is in the <b>Paused</b> state. The

<i>frame</i> value describes the top frame on the JavaScript stack; see

[[#Frames|frames]], below. The <i>reason</i> value describes why the thread

paused. It has one of the following forms:

The thread stopped at the breakpoint represented by the actor named

<i>actor</i>.

The thread stopped at the breakpoint represented by the actor named

<i>actor</i>.

The client had asked the thread to step to the next statement, and the

thread completed that step.

The client had asked the thread to pause before making each function call,

and the thread is about to call a function. Single-stepping the thread will

place it at the head of the function's code, with all arguments, local

variables, and local functions bound.

The client had asked the thread to pause before returning from functions,

and the thread is about to return from a function. Single-stepping the

thread will return the thread to the calling frame.

The client had asked the thread to pause before throwing an exception;

<i>grip</i> is the name of an actor representing the exception value being

thrown. Control is still at the point of the throw; it has not yet passed

to a catch clause. Single-stepping this thread will report either a

"caught" or "uncaught" pause.

The client stepped the thread from a "pre-throw" pause, and a catch clause

has been found for the exception referred to by <i>grip</i>; control is

stopped at the head of the catch clause, with catch variable bindings made.

If the catch is conditional, control is at the beginning of the condition.

The client stepped the thread from a "pre-throw" pause, and no catch clause

was found for the exception. <i>(I'm not sure which code the thread is

executing at this point; we might as well reveal SpiderMonkey's natural

behavior.)</i>

The thread had been stopped in a conditional guard, and the client asked

the thread to continue but pause before throwing an exception. The guard

condition evaluated to false, and the thread is about to re-throw the

exception value, <i>grip</i>.

If a thread is in the <b>Paused</b> state, the client can resume it by

sending a packet of the following form:

   { "to":<i>thread</i>, "type":"attach", "pause-for":<i>events</i> }

This puts the thread in the <b>Running</b> state, but asks it to pause if

any of the event described by <i>events</i> occurs. The form of

<i>events</i> is described in [[#Events]].

If a thread is in the <b>Running</b> state, the client can cause it to

pause where it is by sending a packet of the following form:

This indicates that the thread stopped due to the client's

<tt>interrupt</tt> packet, and is now in the <b>Paused</b> state.

   { "from":<i>thread</i>, "type":"paused", "frame":<i>frame</i>, "reason":<i>reason</i> }

This indicates that the thread stopped of its own accord before receiving

the client's <tt>interrupt</tt> packet, and is now in the <b>Paused</b>

state. The meanings of the thread's packet's properties are as for an

ordinary pause. The thread will ignore the client's interrupt packet when

it receives it.

This indicates that the thread exited before receiving the client's

<tt>interrupt</tt> packet, and is now in the <b>Exited</b> state. See

[[#Exiting_Threads|Exiting Threads]], below.

This allows the thread actor name, <i>thread</i>, to be reused for other actors.

= Events =