Confirmed users
497
edits
Remote Debugging Protocol: Difference between revisions
Jump to navigation
Jump to search
→Thread Interactions
m (→Actors) |
|||
| Line 43: | Line 43: | ||
Packets not described as "requests" or "replies" are part of some more complicated interaction, which should be spelled out in more detail. | Packets not described as "requests" or "replies" are part of some more complicated interaction, which should be spelled out in more detail. | ||
= | = The Root Actor = | ||
Actors representing threads of JavaScript execution follow a more | When the connection to the server is opened, the root actor opens the conversation with the following packet: | ||
{ from:0, application-type:<i>app-type</i>, traits:<i>traits</i>, ...} | |||
The root actor's name is always zero. <i>app-type</i> is a JSON string indicating what sort of program the server represents. There may be more properties present, depending on <i>app-type</i>. | |||
<i>traits</i> is a JSON object describing protocol variants this server supports that are not convenient for the client to detect otherwise. The property names present indicate what traits the server has; the properties' values depend on their names. This version of the protocol defines no traits, so <i>traits</i> must be a JSON object with no properties, {}. | |||
For web browsers, the introductory packet should have the following form: | |||
{ from:0, application-type:"browser", traits:<i>traits</i> } | |||
== Listing Top-Level Browsing Contexts == | |||
To get a list of the top-level browsing contexts present in a browser, a client should send a packet like the following to the root actor: | |||
{ to:0, type:"list-contexts" } | |||
The response should have the form: | |||
{ from:0, contexts: [<i>CONTEXT</i>...] } | |||
The 'contexts' property is a list with one element for each top-level browsing context present in the browser. Each <i>CONTEXT</i> has the following form: | |||
{ actor:<i>ACTOR</i>, title:<i>TITLE</i>, url:<i>URL</i> } | |||
<i>ACTOR</i> is the actor representing that top-level browsing context; <i>TITLE</i> is the context's document's title, and <i>URL</i> is the context's document's URL. | |||
Clients should send "list-contexts" requests only to root actors that have identified themselves as browsers. | |||
Actor names given in a list-contexts reply are valid until the next list-contexts request is received, unless the client attaches to them. An attached context actor name is valid until the client detaches from the context and receives a "detached" packet from the context, or until the client receives an "exited" packet from the context. See "Interacting with Thread-Like Actors" for details. | |||
For example, upon connection to a web browser visiting two pages at example.com, the root actor's introductory packet might look like this: | |||
{ from:0, application-type:"browser", traits:{} | |||
contexts: [ { actor:1, title:"Fruits", | |||
url:"http://www.example.com/fruits/"}, | |||
{ actor:2, title:"Bats", | |||
url:"http://www.example.com/bats/"}]} | |||
<i>(The point here is to give the debugger enough information to select which context it would like to debug without having to do too many round trips. Round trips are bad for UI responsiveness, but large packets are probably not a problem, so whatever would help to add, we should add.)</i> | |||
= Interacting with Thread-Like Actors = | |||
Actors representing independent threads of JavaScript execution, like browsing contexts and web worker threads, are collectively known as "threads". Interactions with actors representing threads follow a more complication communication pattern. | |||
A thread is always in one of the following states: | |||
* <b>Detached</b>: the thread is running freely, and not presently interacting with the debugger. Detached threads run, encounter errors, and exit without exchanging any sort of messages with the debugger. A debugger can attach to a thread, putting it in the "Running" state. Or, a detached thread may exit on its own, entering the "Exited" state. | * <b>Detached</b>: the thread is running freely, and not presently interacting with the debugger. Detached threads run, encounter errors, and exit without exchanging any sort of messages with the debugger. A debugger can attach to a thread, putting it in the "Running" state. Or, a detached thread may exit on its own, entering the "Exited" state. | ||