Confirmed users
496
edits
Remote Debugging Protocol: Difference between revisions
Jump to navigation
Jump to search
m
no edit summary
m (Typos.) |
mNo edit summary |
||
| Line 169: | Line 169: | ||
to which the grip actor replies: | to which the grip actor replies: | ||
{ "from":<i>grip-actor</i>, "prototype":<i>prototype</i>, | { "from":<i>grip-actor</i>, "prototype":<i>prototype</i>, "own-properties":<i>own-properties</i> } | ||
where <i>prototype</i> is a grip on the object's prototype (possibly <tt>{ "type":"null" }</tt>), and <i>own-properties</i> has the form: | where <i>prototype</i> is a grip on the object's prototype (possibly <tt>{ "type":"null" }</tt>), and <i>own-properties</i> has the form: | ||
{ <i>name</i>:<i>descriptor</i>, ... } | { <i>name</i>:<i>descriptor</i>, ... } | ||
| Line 244: | Line 243: | ||
== Grip Lifetimes == | == Grip Lifetimes == | ||
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-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. | ||
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 | 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 pause-lifetime and thread-lifetime 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 288: | Line 289: | ||
This refers to line <i>line</i>, column <i>column</i> of the source code passed to the call to the <tt>Function</tt> constructor at <i>location</i>. To distinguish the different texts passed to eval, each is assigned a unique integer, <i>id</i>. | This refers to line <i>line</i>, column <i>column</i> of the source code passed to the call to the <tt>Function</tt> constructor at <i>location</i>. To distinguish the different texts passed to eval, each is assigned a unique integer, <i>id</i>. | ||
As indicated, locations can be nested | As indicated, locations can be nested. A location like this one: | ||
{ "eval":{ "eval":{ "url":"file:///home/example/sample.js", "line":20 } | { "eval":{ "eval":{ "url":"file:///home/example/sample.js", "line":20 } | ||
"line":30 } | "id":300, "line":30 } | ||
"line":40 } | "id":400, "line":40 } | ||
refers to line 40 of the code passed to the call to eval occurring on line 30 of the code passed to the call to eval on line 20 of <tt>file:///home/example/sample.js</tt>. | refers to line 40 of the code passed to the call to eval occurring on line 30 of the code passed to the call to eval on line 20 of <tt>file:///home/example/sample.js</tt>. | ||
| Line 350: | Line 351: | ||
* <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 <b>Paused</b> state. The debugger can also interrupt a running thread; this elicits a response and puts the thread in the <b>Paused</b> state. A running thread may also exit, entering the <b>Exited</b> 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 <b>Paused</b> state. The debugger can also interrupt a running thread; this elicits a response and puts the thread in the <b>Paused</b> state. A running thread may also exit, entering the <b>Exited</b> 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 <b>Running</b> 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 <b>Running</b> state. If the client detaches from the thread, it returns to the <b>Detached</b> state. | ||
* <b>Exited</b>: the thread has ceased execution, and will disappear. The resources of the underlying thread may have been freed; this state | * <b>Exited</b>: the thread has ceased execution, and will disappear. The resources of the underlying thread may have been freed; this state merely indicates that the actor's name is not yet available for reuse. When the actor receives a "release" packet, the name may be reused. | ||
[[File:thread-states.png]] | [[File:thread-states.png]] | ||
| Line 602: | Line 603: | ||
{ "actor":<i>actor</i>, "depth":<i>depth</i>, "id":<i>id</i>, | { "actor":<i>actor</i>, "depth":<i>depth</i>, "id":<i>id</i>, | ||
"type":"call", | "type":"call", "where":<i>location</i>, "environment",<i>environment</i>, | ||
"callee":<i>callee</i>, "callee-name":<i>callee-name</i>, "this":<i>this</i>, "arguments":<i>arguments</i> } | |||
"callee":<i>callee</i>, "callee-name":<i>callee-name</i>, | |||
where: | where: | ||
| Line 625: | Line 624: | ||
{ "actor":<i>actor</i>, "depth":<i>depth</i>, "id":<i>id</i>, | { "actor":<i>actor</i>, "depth":<i>depth</i>, "id":<i>id</i>, | ||
"type":"host-call", | "type":"host-call", | ||
"callee":<i>callee</i>, "callee-name":<i>callee-name</i>, | "callee":<i>callee</i>, "callee-name":<i>callee-name</i>, "this":<i>this</i>, "arguments":<i>arguments</i> } | ||
where the properties are as defined above. (Compared to an ordinary call, the <tt>where</tt> and <tt>environment</tt> properties are missing.) | where the properties are as defined above. (Compared to an ordinary call, the <tt>where</tt> and <tt>environment</tt> properties are missing.) | ||