Confirm
496
edits
Changes
Revisions based on Panos's implementation notes. https://github.com/jimblandy/DebuggerDocs/commit/f2344f17e4f3aa2a99b6ab0702d782e09398e45d
where <i>message</i> provides details to help debugger developers understand what went wrong: what kind of actor <i>actor</i> is; the packet received; and so on.
If an actor recieves a packet which is missing needed parameters (say, a <tt>"releaseMany"</tt> packet with no <tt>"actors"</tt> parameter), it sends an error reply of the form:
{ "from":<i>actor</i>, "error":"missingParameter", "message":<i>message</i> }
where <i>message</i> provides details to help debugger developers fix the problem.
If an actor recieves a packet with a parameter whose value is inappropriate for the operation, it sends an error reply of the form:
{ "from":<i>actor</i>, "error":"badParameterType", "message":<i>message</i> }
where <i>message</i> provides details to help debugger developers fix the problem. (Some packets' descriptions specify more specific errors for particular circumstances.)
= Grips =
{ "from":<i>functionGripActor</i>, "scope":<i>environment</i> }
where <i>environment</i> is a [[#Lexical_Environments|lexical environment]]. Note that the server only returns environments of functions in a context being debugged; if the function's global scope is not the browsing context to which we are attached, the function grip actor sends an error reply of the form: { "from":<i>functionGripActor</i>, "error":"notDebuggee", "message":<i>message</i> } where <i>message</i> is text explaining the problem.
{ "to":<i>functionGripActor</i>, "type":"decompile", "pretty":<i>pretty</i> }
where <i>code</i> is a string.
If <i>functionGripActor</i>'s referent is not a function, or is a function proxy, the actor responds to these requests with an error reply of the form:
{ "from":<i>functionGripActor</i>, "error":"objectNotFunction", message:<i>message</i> }
where <i>message</i> is a string containing any additional information that would be helpful to debugger developers.
== Long Strings ==
{ "from":<i>gripActor</i> }
This closes the grip actor. The <tt>"release"</tt> packet may only be sent to thread-lifetime grip actors; if a pause-lifetime grip actor receives a <tt>"release"</tt> packet, it sends an error reply of the form: { "from":<i>gripActor</i>, "error":"notReleasable", "message":<i>message</i> } where <i>message</i> includes whatever further information would be useful to the debugger developers.
The client can release many thread-lifetime grips in a single operation by sending the thread actor a request of the form:
Regardless of the lifetime of a grip, the client may only send messages to grip actors while the thread to which they belong is paused; the client's interaction with values cannot take place concurrently with the thread.
= Completion Values =
Some packets describe the way a stack frame's execution completed using a <b>completion value</b>, which takes one of the following forms:
{ "return":<i>grip</i> }
This indicates that the frame completed normally, returning the value given by <i>grip</i>.
{ "throw":<i>grip</i> }
This indicates that the frame threw an exception; <i>grip</i> is the exception value thrown.
{ "terminated":true }
This indicates that the frame's execution was terminated, as by a "slow script" dialog box or running out of memory.
= Source Locations =
{ "type":"resumeLimit" }
The client resumed the thread with a <tt>"resume" </tt> packet that included a <tt>resumeLimit</tt> property, and the thread paused because the given <i>limit</i> was met. Execution remains in the frame the thread was resumed in, and that frame is not about to be popped. { "type":"resumeLimit", "frameFinished":<i>completion</i> } The client resumed the thread with a <tt>"resume"</tt> packet that included a <tt>resumeLimit</tt> property, and the thread paused because the frame is about to be popped. <i>Completion</i> is a [[#Completion_Values|completion value]] describing how the frame's execution ended. The frame being popped is still the top frame on the stack, but subsequent <code>"resume"</code> operations will run in the calling frame.
{ "type":"debuggerStatement" }
<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":"clientEvaluated", "valueframeFinished":<i>gripcompletion</i> }
The expression given in the client's prior <tt>clientEvaluate</tt> command has completed normallyexecution; <i>gripcompletion</i> is a grip on the expression's value. See [[#Evaluating_Source-Language_ExpressionsCompletion_Values|Evaluating Source-Language Expressionscompletion value]] for detailsdescribing how it completed. { "type":"clientEvaluated", "exception":<i>grip</i> } The client's prior frame created for the <tt>clientEvaluate</tt> command resumption has completed abruptly; <i>grip</i> is been popped from the uncaught exception valuestack. See [[#Evaluating_Source-Language_Expressions|Evaluating Source-Language Expressions]] for details.
== Resuming a Thread ==
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":"resume", "resumeLimit":<i>limit</i> }
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.
{ "type":"next" }
This is the same as <tt>"next"</tt>, except that it steps into calls.
When a thread pauses because a limit was reached, the "paused" packet's <i>reason</i> will have a type of <tt>"resumeLimit"</tt>.
A resume limit applies only to the current resumption; once the thread pauses, whether because the limit was reached or some other event occurred—a breakpoint hit, for example—the resume limit is no longer in effect.
If no <tt>"resumeLimit"</tt> property appears in the <tt>"resume" </tt> packet, then the thread should run until some standing pause condition is met (a breakpoint is hit; a watchpoint triggers; or the like). To force the current frame to end execution immediately, the client can send a packet of the form: { "to":<i>thread</i>, "type":"resume", "forceCompletion":<i>completion</i> } where <i>completion</i> is a [[#Completion_Values|completion value]] indicating whether the frame should return a value, throw an exception, or be terminated. A <tt>"resume"</tt> packet may not include both a <tt>"resumeLimit"</tt> property and a <tt>"forceCompletion"</tt> property.
A <tt>"resume" </tt> packet closes the pause actor the client provided in the "paused" packet that began the pause.
If the client sends a <code>"resume"</code> packet to a thread that is not in the <b>Paused</b> state, the actor sends an error reply of the form:
and other properties are as above.
The argument list may be incomplete or inaccurate, for various reasons. If the program has assigned to its formal parameters, the original values passed may have been lost, and compiler optimizations may drop some argument values.
== Evaluating Source-Language Expressions ==
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":"clientEvaluate", "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 top of <i>thread</i>'s current stack, using the stackenvironment of <i>frame</i>. <i>Frame</i> must be a live actor for one of <i>thread</i>'s frames, and the given frame must be one from which we can retrieve a lexical environment; that is, it must not be the frame for a call to a non-debuggee function. When evaluation of <i>expr</i> completes, the client will report a <tt>clientEvaluate</tt> pause containing the expression's value.
If evaluating <i>expr</i> completes abruptly, this outcome is still reported via an <tt>clientEvaluated</tt> pause, so it is not necessary for the client to take explicit steps to catch exceptions thrown by the expression.
If <i>frame</i> is not the name of an actor for a frame currently on <i>thread</i>'s stack, the thread actor sends a reply of the form:
{ "from":<i>thread</i>, "error":"unknownFrame", "message":<i>message</i> }
where <i>message</i> provides any details that would be helpful to the debugger developers. In this case, the thread's state is unaffected.
If <i>frame</i> is not a frame whose environment we can access, the thread actor sends an error reply of the form:
{ "from":<i>thread</i>, "error":"notDebuggee", "message":<i>message</i> }
where <i>message</i> provides further appropriate details.
If the client sends a <code>"clientEvaluate"</code> packet to a thread that is not in the <b>Paused</b> state, the actor sends an error reply of the form:
{ "from":<i>thread</i>, "error":"wrongState", "message":<i>message</i> }
where <i>message</i> details which state the thread was in instead (to make debugging debuggers easier). In this case, the thread's state is unaffected.
<i>TODO: evaluate with given grips bound to given identifiers</i>
