Remote Debugging Protocol: Difference between revisions

Jump to navigation Jump to search

Remote Debugging Protocol (view source)

Revision as of 22:33, 17 May 2011

2,338 bytes removed ,  17 May 2011
Simplify pause types, and make them more like the usual debugger 'next', 'step', 'continue', and 'finish'.
(Let frame actors live as long as the frames to which they refer. Notify the client of each frame actor's demise.)
(Simplify pause types, and make them more like the usual debugger 'next', 'step', 'continue', and 'finish'.)
Line 405: Line 405:
To attach to a thread, the client sends a packet of the form:
To attach to a thread, the client sends a packet of the form:


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


Here, <i>thread</i> is the actor representing the thread, perhaps a browsing context from a "list-contexts" reply. This tells the thread to continue to run, but asks it to pause if any of the events described by <i>pause-types</i> occurs. The form of <i>pause-types</i> is described in [[#Pause_Types|Pause Types]].
Here, <i>thread</i> is the actor representing the thread, perhaps a browsing context from a "list-contexts" reply. This packet causes the thread to pause its execution, if it does not exit of its own accord first. The thread responds in one of two ways:


The thread responds in one of two ways:
  { "from":<i>thread</i>, "type":"paused", "why":{ "type":"attached" }, ... }


  { "from":<i>thread</i>, "type":"attached" }
The thread is now in the <b>Paused</b> state, because the client has attached to it. The actor name <i>thread</i> remains valid until the client detaches from the thread or acknowledges a thread exit. This is an ordinary <code>"paused"</code> packet, whose form and additional properties are as described in [#Thread_Pauses|Thread Pauses], below.
 
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.


   { "from":<i>thread</i>, "type":"exited" }
   { "from":<i>thread</i>, "type":"exited" }


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 thread exited on its own before receiving the "attach" packet. The thread is now in the <b>Exited</b> state. The client should follow by sending a "release" packet; see [[#Exiting_Threads|Exiting Threads]], below.


== Detaching From a Thread ==
== Detaching From a Thread ==
Line 480: Line 478:
<i>TODO: This should provide more details about the watchpoint in the packet, instead of incurring another round-trip before we can display anything helpful.</i>
<i>TODO: This should provide more details about the watchpoint in the packet, instead of incurring another round-trip before we can display anything helpful.</i>


   { "type":"stepped" }
   { "type":"pause-for" }


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 resume, and the thread paused because the <i>pause-condition</i> given in the "resume" request was met.
 
  { "type":"pre-call" }
 
The client had asked the thread to pause before making each function call, and the thread is about to call a function. (Requesting the next value from an iterator, whether via the <tt>next</tt> or <tt>send</tt> methods, is considered a call for the purposes of these packets.) Single-stepping the thread will a place it at the head of the function's code, with all arguments, local variables, and local functions bound.
 
  { "type":"pre-return" }
 
The client had asked the thread to pause before returning from functions, and the thread is about to return from a function. (The JavaScript 1.7 <tt>yield</tt> operator is treated as a kind of return, for the sake of these packets.) Single-stepping the thread will return the thread to the calling frame.
 
  { "type":"pre-throw", "exception":<i>grip</i> }
 
The client had asked the thread to pause before throwing an exception; <i>grip</i> is a grip on 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.
 
  { "type":"caught", "exception":<i>grip</i> }
 
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.
 
  { "type":"uncaught", "exception":<i>grip</i> }
 
The client stepped the thread from a "pre-throw" pause, and no catch clause was found for the exception. <i>Grip</i> is as above. <i>(I'm not sure which code the thread is executing at this point; we might as well reveal SpiderMonkey's natural behavior.)</i>
 
  { "type":"pre-throw-by-guard", "exception":<i>grip</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>.


   { "type":"client-evaluated", "value":<i>grip</i> }
   { "type":"client-evaluated", "value":<i>grip</i> }
Line 516: Line 490:
The client's prior <tt>client-evaluate</tt> command has completed abruptly; <i>grip</i> is the uncaught exception value. See [[#Evaluating_Source-Language_Expressions|Evaluating Source-Language Expressions]] for details.
The client's prior <tt>client-evaluate</tt> command has completed abruptly; <i>grip</i> is the uncaught exception value. See [[#Evaluating_Source-Language_Expressions|Evaluating Source-Language Expressions]] for details.


=== Pause Types ===
  { "type":"attached" }


The <tt>pause-for</tt> property of an <tt>attach</tt> or <tt>resume</tt> packet (written as <i>pause-types</i>) is an object whose properties' names indicate which events the client is interested in. The vocabulary of names is the same as that of pause <tt>reason</tt> types, listed [[#Thread_Pauses|above]]. If a property's value in a <i>pause-type</i> is <tt>true</tt>, then the event is of interest.
The thread paused because the client attached to it.


For example, the following <i>resume</i> packet would instruct <i>thread</i> to continue until the thread is about to return from a function or is about to throw an exception:
== Resuming a Thread ==


  { "to":<i>thread</i>, "type":"resume",
If a thread is in the <b>Paused</b> state, the client can resume it by sending a packet of the following form:
    "pause-for":{ "pre-return":true, "pre-throw":true } }


Certain pause types cause other pause types to be included automatically, if those pause types are not mentioned explicitly in <i>pause-types</i>:
  { "to":<i>thread</i>, "type":"resume", "pause-for":<i>pause-condition</i> }


{| frame="box" rules="all" cellpadding="8"
This puts the thread in the <b>Running</b> state. The thread will pause again for breakpoint hits, watchpoint hits, throw watches, frame pop watches, and other standing pause requests.
! Pause type
! Also implies, if not mentioned explicitly
|-
| <tt>pre-throw</tt>
| <tt>pre-throw-by-guard</tt>
|}


For some pause types, the property's value can provide additional detail.
In addition, if the optional <tt>pause-for</tt> property is present, then the thread should also pause if <i>pause-condition</i> is satisfied. <i>Pause-condition</i> must have one of the following forms:


To request that the thread pause before returning from a specific frame, the <i>pause-types</i> object can include a property of the form:
  { "type":"next" }


  { ... "pre-return":<i>frame-actor</i> ... }
The thread should pause:
<ul>
<li>just before the current frame is popped, whether by throwing an exception or returning a value; or
<li>when control in the current frame reaches a different statement than the one it is currently at.
</ul>
Note that execution in frames younger than the current frame never meets this condition; a <tt>"next"</tt> steps over calls, generator-iterator invocations, and so on.


where <i>frame-actor</i> is the name of the actor representing a specific stack frame, as given in the reply to a <tt>frames</tt> request.
  { "type":"step" }


=== Extending The Protocol With New Pause Types ===
The thread should pause:
<ul>
<li>just before the current frame is popped, whether by throwing an exception or returning a value; or
<li>just after a new frame is pushed; or
<li>when control in the current frame reaches a different statement than the one it is currently
at.
</ul>
This is the same as <tt>"next"</tt>, except that it steps into calls.


The format of <i>reason</i> values in <tt>paused</tt> packets should be treated as a point of extension, with application-specific pause types added as the need arises. DOM events, DOM mutation, and web worker message transmission might all be interesting pause types. Debuggers unprepared for a particular event type will simply not request that type in the <tt>pause-for</tt> properties of its <tt>attach</tt> and <tt>resume</tt> packets, so extending the events a server supports should not disturb existing clients.
  { "type":"finish" }


== Resuming a Thread ==
The thread should pause just before the current frame is popped, whether by throwing an exception or returning a value.


If a thread is in the <b>Paused</b> state, the client can resume it by sending a packet of the following form:
When a thread pauses because a <i>pause-condition</i> was met, the "paused" packet's <i>reason</i> will have a type of <tt>"pause-for"</tt>.


  { "to":<i>thread</i>, "type":"resume", "pause-for":<i>pause-types</i> }
A pause condition applies only to the current resumption; once the thread pauses, whether because the condition was met or some other event occurred&mdash;a breakpoint hit, for example&mdash;the pause condition is no longer in effect.


This puts the thread in the <b>Running</b> state, but asks it to pause if any of the event described by <i>pause-types</i> occurs. The form of <i>pause-types</i> is described in [[#Pause_Types|Pause Types]].
If no <tt>"pause-for"</tt> property appears in the "resume" packet, then the thread should run until a standing pause request's conditions are satisfied (breakpoint, watchpoint, or the like).


A "resume" packet closes the pause actor the client provided in the "paused" or "interrupted" packet that began the pause.
A "resume" packet closes the pause actor the client provided in the "paused" or "interrupted" packet that began the pause.
Line 701: Line 680:
To evaluate a source-language expression in a thread, the client sends a specialized <tt>resume</tt> packet of the form:
To evaluate a source-language expression in a thread, the client sends a specialized <tt>resume</tt> packet of the form:


   { "to":<i>thread</i>, "type":"client-evaluate", "expression":<i>expr</i>, "frame":<i>frame</i>, "pause-for":<i>pause-types</i> }
   { "to":<i>thread</i>, "type":"client-evaluate", "expression":<i>expr</i>, "frame":<i>frame</i> }


This resumes the thread just as an ordinary <tt>resume</tt> packet does, but rather than continuing execution where the pause took place, has the thread begin evaluation of the source-language expression given by <i>expr</i>, a string. The evaluation takes place in a new [[#Client_Evaluation_Frames|Client Evaluation Frame]], pushed on the stack. When evaluation of <i>expr</i> completes, the client will report a <tt>client-evaluate</tt> pause containing the expression's value.
This resumes the thread just as an ordinary <tt>resume</tt> packet does, but rather than continuing execution where the pause took place, has the thread begin evaluation of the source-language expression given by <i>expr</i>, a string. The evaluation takes place in a new [[#Client_Evaluation_Frames|Client Evaluation Frame]], pushed on the stack. When evaluation of <i>expr</i> completes, the client will report a <tt>client-evaluate</tt> pause containing the expression's value.
Jimb
Confirmed users
497

edits

Retrieved from "https://wiki.mozilla.org/Special:MobileDiff/309808"

Navigation menu