Confirmed users
497
edits
Remote Debugging Protocol: Difference between revisions
Jump to navigation
Jump to search
Deleting breakpoints.
(Add object property access requests.) |
(Deleting breakpoints.) |
||
| Line 15: | Line 15: | ||
For example, a debugger might connect to a browser, ask the root actor to list the browser's tabs, and present this list to the developer. If the developer chooses some tabs to debug, then the debugger can send <tt>attach</tt> requests to the actors representing those tabs, to begin debugging. | For example, a debugger might connect to a browser, ask the root actor to list the browser's tabs, and present this list to the developer. If the developer chooses some tabs to debug, then the debugger can send <tt>attach</tt> requests to the actors representing those tabs, to begin debugging. | ||
To allow the server to reuse actor names and the resources they require, actors have limited lifetimes. All actors in a server form a tree, whose root is the root actor. Closing communications with an actor automatically closes communications with its descendants. For example, the actors representing a thread's stack frames are children of the actor representing the thread itself, so that when a debugger detaches from a thread, which closes the thread's actor, the frames' actors are automatically closed. This arrangement allows the protocol to mention actors liberally, without making the client responsible for explicitly closing every actor that has ever been mentioned. | To allow the server to reuse actor names and the resources they require, actors have limited lifetimes. All actors in a server form a tree, whose root is the root actor. Closing communications with an actor automatically closes communications with its descendants. For example, the actors representing a thread's stack frames are children of the actor representing the thread itself, so that when a debugger detaches from a thread, which closes the thread's actor, the frames' actors are automatically closed. This arrangement allows the protocol to mention actors liberally, without making the client responsible for explicitly closing every actor that has ever been mentioned. | ||
When we say that some actor <i>A</i> is a <b>child</b> of some actor <i>B</i>, we mean that <i>A</i> is a direct child of <i>B</i>, not a grandchild, great-grandchild, or the like. Similarly, <b>parent</b> means "direct parent". We use the terms <b>ancestor</b> and <b>descendent</b> to refer to those looser relationships. | |||
The root actor has no parent, and lives as long as the underlying connection to the client does; when that connection is closed, all actors are closed. | The root actor has no parent, and lives as long as the underlying connection to the client does; when that connection is closed, all actors are closed. | ||
Note that the actor hierarchy does not, in general, correspond to any particular hierarchy appearing in the debuggee. For example, although web workers are arranged in a hierarchy, the actors representing web worker threads are all | Note that the actor hierarchy does not, in general, correspond to any particular hierarchy appearing in the debuggee. For example, although web workers are arranged in a hierarchy, the actors representing web worker threads are all children of the root actor: one might want to detach from a parent worker while continuing to debug one of its children, so it doesn't make sense to close communications with a child worker simply because one has closed communications with its parent. | ||
<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> | <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> | ||
| Line 210: | Line 212: | ||
where <i>descriptor</i> is a descriptor for the given property, or <tt>null</tt> if there is no such property on the object. | where <i>descriptor</i> is a descriptor for the given property, or <tt>null</tt> if there is no such property on the object. | ||
<i>TODO: assign to value property</i> | |||
<i>TODO: special stuff for arrays</i> | <i>TODO: special stuff for arrays</i> | ||
| Line 237: | Line 241: | ||
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 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. | 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 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. | ||
However, in some cases the client may wish to retain a reference to an object while the debuggee runs. For example, a panel displaying objects selected by the user must update its view of the objects each time the debuggee pauses. To carry this out, the client can promote a pause-lifetime grip to a <b>thread-lifetime</b> grip, which lasts until the thread is detached from or exits. Actors in thread-lifetime grips are | However, in some cases the client may wish to retain a reference to an object while the debuggee runs. For example, a panel displaying objects selected by the user must update its view of the objects each time the debuggee pauses. To carry this out, the client can promote a pause-lifetime grip to a <b>thread-lifetime</b> grip, which lasts until the thread is detached from or exits. Actors in thread-lifetime grips are children of the thread actor. When the client no longer needs a thread-lifetime grip, it can explicitly release it. Both kinds of grips are garbage collection roots. | ||
To promote a pause-lifetime grip to a thread-lifetime grip, the client sends a packet of the form: | To promote a pause-lifetime grip to a thread-lifetime grip, the client sends a packet of the form: | ||
| Line 715: | Line 719: | ||
If evaluating <i>expr</i> completes abruptly, this outcome is still reported via an <tt>client-evaluated</tt> pause, so it is not necessary for the client to take explicit steps to catch exceptions thrown by the expression. | If evaluating <i>expr</i> completes abruptly, this outcome is still reported via an <tt>client-evaluated</tt> pause, so it is not necessary for the client to take explicit steps to catch exceptions thrown by the expression. | ||
<i>TODO: evaluate with given grips bound to given identifiers</i> | |||
= Breakpoints = | |||
While a thread is paused, a client can set breakpoints in the thread's code by sending requests of the form: | While a thread is paused, a client can set breakpoints in the thread's code by sending requests of the form: | ||
| Line 725: | Line 731: | ||
{ "from":<i>thread</i>, "actor":<i>actor</i>, "actual-location":<i>actual-location</i> } | { "from":<i>thread</i>, "actor":<i>actor</i>, "actual-location":<i>actual-location</i> } | ||
where <i>actor</i> is an actor representing the breakpoint, and <i>actual-location</i> is the location at which the breakpoint was really set. If <i>location</i> and <i>actual-location</i> are the same, then the <tt>actual-location</tt> property can be omitted. | where <i>actor</i> is an actor representing the breakpoint (a child of the thread actor), and <i>actual-location</i> is the location at which the breakpoint was really set. If <i>location</i> and <i>actual-location</i> are the same, then the <tt>actual-location</tt> property can be omitted. | ||
If the thread cannot find the script referred to in <i>location</i>, it sends an error reply of the form: | If the thread cannot find the script referred to in <i>location</i>, it sends an error reply of the form: | ||
| Line 735: | Line 741: | ||
{ "from":<i>thread</i>, "error":"no-code-at-line-column" } | { "from":<i>thread</i>, "error":"no-code-at-line-column" } | ||
To delete a breakpoint, the client can send the breakpoint's actor a message of the form: | |||
{ "to":<i>breakpoint-actor</i>, "type":"delete" } | |||
to which the breakpoint actor will reply, simply: | |||
{ "from":<i>breakpoint-actor</i> } | |||
This closes communications with <i>breakpoint-actor</i>. | |||
== Frame Pop Watches | = Watchpoints = | ||
= Frame Pop Watches = | |||
<i>TODO: DOM node inspection, highlighting</i> | <i>TODO: DOM node inspection, highlighting</i> | ||