Changes

The protocol operates at the JavaScript level, not at the C++ or machine level, and assumes that the JavaScript implementation itself is healthy and responsive. The JavaScript program being executed may well have gone wrong, but the JavaScript implementation's internal state must not be corrupt. Bugs in the implementation may cause the debugger to fail; bugs in the interpreted program must not.

An <b>actor</b> is something on the server that can exchange JSON packets with the client. Every packet from the client specifies the actor to which it is directed, and every packet from the server indicates which actor sent it.

<i>(We are stealing the "actor" terminology from Mozilla's [[IPDL]], to mean, roughly, "things participating in the protocol". However, IPDL does much more with the idea than we do: it treats both client and server as collections of actors, and uses that detail to statically verify properties of the protocol. In contrast, the debugging protocol simply wants a consistent way to indicate the entities to which packets are directed.)</i>

The protocol is carried by a reliable, bi-directional byte stream; data sent in both directions consists of JSON objects, called packets. A packet is a top-level JSON object, not contained inside any other value.

Clients should silently ignore packet properties they do not recognize. We expect that, as the protocol evolves, we will specify new properties that can appear in existing packets, and experimental implementations will do the same.

In this protocol description, a <b>request</b> is a packet sent from the client which always elicits a single packet from the recipient, the <b>reply</b>. These terms indicate a simple pattern of communication: at any given time, either the client or actor is permitted to send a packet to the other, but never both.

where <i>message</i> provides details to help debugger developers fix the problem. (Some packets' descriptions specify more specific errors for particular circumstances.)

A grip is a JSON value that refers to a specific JavaScript value in the debuggee. Grips appear anywhere an arbitrary value from the debuggee needs to be conveyed to the client: stack frames, object property lists, lexical environments, <tt>paused</tt> packets, and so on.

Garbage collection will never free objects visible to the client via the protocol. Thus, actors representing JavaScript objects are effectively garbage collection roots.

While a thread is paused, the client can send requests to the actors appearing in object grips to examine the objects they represent in more detail.

Protocol requests that describe objects' properties to the client often use <b>descriptors</b>, JSON values modeled after ECMAScript 5's property descriptors, to describe individual properties.

}

To examine an object's prototype and properties, a client can send the object's grip's actor a request of the form:

<i>TODO: What about objects with many properties?</i>

To find an object's prototype, a client can send the object's grip's actor a request of the form:

where <i>prototype</i> is a grip on the object's prototype (possibly <tt>{ "type":"null" }</tt>).

To list an object's own properties' names, a client can send the object's grip's actor a request of the form:

where each <i>name</i> is a string naming an own property of the object.

To obtain a descriptor for a particular property of an object, a client can send the object's grip's actor a request of the form:

<i>TODO: descriptors for Harmony proxies</i>

If an object's class as given in the grip is <code>"Function"</code>, then the grip's actor responds to the messages given here.

where <i>message</i> is a string containing any additional information that would be helpful to debugger developers.

The client can find the full contents of a long string by sending a request to the long string grip actor of the form:

As with any other actor, the client may only send messages to a long string grip actor while it is alive: for [[#Grip_Lifetimes|pause-lifetime grips]], until the debuggee is resumed; or for [[#Grip_Lifetimes|thread-lifetime grips]], until the thread is detached from or exits. However, unlike object grip actors, the client may communicate with a long string grip actor at any time the actor is alive, regardless of whether the debuggee is paused. (Since strings are immutable values in JavaScript, the responses from a long string grip actor cannot depend on the actions of the debuggee.)

Most grips are <b>pause-lifetime</b> grips: they last only while the JavaScript thread is paused, and become invalid as soon as the debugger allows the thread to resume execution. (The actors in pause-lifetime grips are children of an actor that is closed when the thread resumes, or is detached from.) This arrangement allows the protocol to use grips freely in responses without requiring the client to remember and close them all.

Regardless of the lifetime of a grip, the client may only send messages to object grip actors while the thread to which they belong is paused; the client's interaction with mutable values cannot take place concurrently with the thread.

Some packets describe the way a stack frame's execution completed using a <b>completion value</b>, which takes one of the following forms:

This indicates that the frame's execution was terminated, as by a "slow script" dialog box or running out of memory.

Many packets refer to particular locations in source code: breakpoint requests specify where the breakpoint should be set; stack frames show the current point of execution; and so on.