Confirm
496
edits
Changes
[master 0bc6982] Merge/tweak fitzgen's black-boxing protocol changes.
Where each <i>sourceForm</i> has the following form:
{ 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.
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 ==
where each <i>frame</i> has the form:
{ "actor":<i>actor</i>, "depth":<i>depth</i>, "type":<i>type</i>, "this":<i>this</i>, ... }
where:
A frame for global code has the form:
{ "actor":<i>actor</i>, "depth":<i>depth</i>, "type":"global", "this":<i>this</i>, "where":<i>location</i>, "source":<i>source</i>, "environment":<i>environment</i> }
where:
* <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>source</i> is a source form as described in [[#Loading_Script_Sources|Loading Script Sources]]
and other properties are as above.
