Confirmed users
496
edits
Remote Debugging Protocol: Difference between revisions
[master 0bc6982] Merge/tweak fitzgen's black-boxing protocol changes.
([master 821a90d] Tweak description of 'sources' request and source actors.) |
([master 0bc6982] Merge/tweak fitzgen's black-boxing protocol changes.) |
||
| Line 833: | Line 833: | ||
Where each <i>sourceForm</i> has the following form: | Where each <i>sourceForm</i> has the following form: | ||
{ actor: <i>sourceActorID</i>, url: <i>sourceURL</i> } | { actor: <i>sourceActorID</i>, | ||
url: <i>sourceURL</i>, | |||
isBlackBoxed: <i>isBlackBoxed</i> } | |||
* <i>sourceActorID</i> is the source actor's id | |||
* <i>sourceURL</i> is the URL of the source represented by the source actor | |||
* <i>isBlackBoxed</i> is a boolean specifying whether the source actor's 'black-boxed' flag is set. See [[#Black_Boxing_Sources|Black Boxing Sources]]. | |||
Each source actor exists throughout the thread's whole lifetime. | Each source actor exists throughout the thread's whole lifetime. | ||
| Line 846: | Line 852: | ||
where <i>contentsOfSource</i> is a grip representing the string of source code: either a JSON string, or a long string grip. (See [[#Grips|Grips]] for a description of long string grips.) | where <i>contentsOfSource</i> is a grip representing the string of source code: either a JSON string, or a long string grip. (See [[#Grips|Grips]] for a description of long string grips.) | ||
=== Black-Boxing Sources === | |||
When debugging a web application that uses large off-the-shelf JavaScript libraries, it may help the developer focus on their own code to treat such libraries as "black boxes", whose internal details are omitted or simplified in the user interface. For example, the user interface could display a sub-chain of stack frames within a black-boxed library as a single element; breakpoints set in a black-boxed library could be disabled; and so on. | |||
Each source actor has a 'black-boxed' flag, and understands requests to set and clear the flag. When a source actor is black-boxed, the debugger does not pause when it hits breakpoints or <code>debugger</code> statements inside that source. If pausing on exceptions is enabled and an exception is thrown inside a black-boxed source, the debugger does not pause until the stack has unwound to a frame in a source that is not black-boxed. | |||
Thread actors still list black-boxed source actors in <code>"sources"</code> replies; and include stack frames running black-boxed code in <code>"frames"</code> requests. However, each <i>sourceForm</i> includes an <code>"isBlackBoxed"</code> property, giving the client all the information it needs to implement the black-boxing behavior in the user interface. | |||
To set a source actor's 'black-boxed' flag: | |||
{ "to": <i>sourceActor</i>, "type": "blackbox" } | |||
The <i>sourceActor</i> responds with a blank response on success: | |||
{ "from": <i>sourceActor</i> } | |||
Or an error response on failure: | |||
{ "from": <i>sourceActor</i>, "error": <i>reason</i> } | |||
To clear a source actor's 'black-boxed' flag: | |||
{ "to": <i>sourceActor</i>, "type": "unblackbox" } | |||
And once again, the <i>sourceActor</i> responds with a blank response on success: | |||
{ "from": <i>sourceActor</i> } | |||
Or an error response on failure: | |||
{ "from": <i>sourceActor</i>, "error": <i>reason</i> } | |||
== Listing Stack Frames == | == Listing Stack Frames == | ||
| Line 861: | Line 899: | ||
where each <i>frame</i> has the form: | where each <i>frame</i> has the form: | ||
{ "actor":<i>actor</i>, "depth":<i>depth</i>, "type":<i>type</i>, "this":<i>this</i>, ... } | { "actor": <i>actor</i>, | ||
"depth": <i>depth</i>, | |||
"type": <i>type</i>, | |||
"this": <i>this</i>, | |||
... } | |||
where: | where: | ||
| Line 878: | Line 920: | ||
A frame for global code has the form: | A frame for global code has the form: | ||
{ "actor":<i>actor</i>, "depth":<i>depth</i>, "type":"global", "this":<i>this</i>, | { "actor":<i>actor</i>, | ||
"where":<i>location</i>, "environment":<i>environment</i> } | "depth":<i>depth</i>, | ||
"type":"global", | |||
"this":<i>this</i>, | |||
"where":<i>location</i>, | |||
"source":<i>source</i>, | |||
"environment":<i>environment</i> } | |||
where: | where: | ||
| Line 885: | Line 932: | ||
* <i>location</i> is the source location of the current point of execution in the global code (see [[#Source_Locations|Source Locations]]); | * <i>location</i> is the source location of the current point of execution in the global code (see [[#Source_Locations|Source Locations]]); | ||
* <i>environment</i> is a value representing the lexical environment of the current point of execution (see [[#Lexical_Environments|Lexical Environments]]); | * <i>environment</i> is a value representing the lexical environment of the current point of execution (see [[#Lexical_Environments|Lexical Environments]]); | ||
* <i>source</i> is a source form as described in [[#Loading_Script_Sources|Loading Script Sources]] | |||
and other properties are as above. | and other properties are as above. | ||