Chromium Code Reviews
chromiumcodereview-hr@appspot.gserviceaccount.com (chromiumcodereview-hr) | Please choose your nickname with Settings | Help | Chromium Project | Gerrit Changes | Sign out
(729)

Issues Search
    My Issues | Starred     Open | Closed | All

Unified Diff: runtime/vm/service/protocol.md

Issue 467183004: Add more types to service/protocol.md (Closed) Base URL: https://dart.googlecode.com/svn/branches/bleeding_edge/dart
Patch Set: alphabetize Created 6 years, 4 months ago
Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.
Jump to:
View side-by-side diff with in-line comments
Download patch
« no previous file with comments | « no previous file | no next file » | no next file with comments »
Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
Index: runtime/vm/service/protocol.md
diff --git a/runtime/vm/service/protocol.md b/runtime/vm/service/protocol.md
index a816685775bb934fc55eebe6c75038b147f6e8ba..07fe3c64ba163ec2c4bcb96529802d4b083258bf 100644
--- a/runtime/vm/service/protocol.md
+++ b/runtime/vm/service/protocol.md
@@ -1,5 +1,8 @@
# Dart VM Service Protocol
+NOTE: The service api is still changing rapidly. If you use the
+service api, expect to encounter non-compatible changes.
+
Description
How to start
JSON
@@ -7,9 +10,18 @@ Websocket
## Types
-Every response returned by the VM Service has the <code>type</code> property. This allows the client distinguish between different kinds of responses. For example, global information about the VM is encoded in an response of type [VM](#VM) and information about an isolate is encoded in an response of type [Isolate](#Isolate).
+Every response returned by the VM Service has the <code>type</code>
+property. This allows the client distinguish between different kinds
+of responses. For example, global information about the VM is encoded
+in an response of type [VM](#VM) and information about an isolate is
+encoded in an response of type [Isolate](#Isolate).
-If the type name of a response begins with an <code>@</code> character then that response is a _reference_. If the type name of a response does not begin with an <code>@</code> character then that response is an _object_ (or sometimes _full object_). A reference is meant to be a subset of a full object with just enough information for the client to generate a reasonable-looking link.
+If the type name of a response begins with an <code>@</code> character
+then that response is a _reference_. If the type name of a response
+does not begin with an <code>@</code> character then that response is
+an _object_ (or sometimes _full object_). A reference is meant to be
+a subset of a full object with just enough information for the client
+to generate a reasonable-looking link.
For example, an isolate reference may look like this...
@@ -22,7 +34,7 @@ For example, an isolate reference may look like this...
... and a full isolate object would have additional properties:
{
- type: "@Isolate",
+ type: "Isolate",
id: "isolates/123",
name: "worker"
entry: ...
@@ -33,9 +45,14 @@ For example, an isolate reference may look like this...
## IDs
-Most responses returned by the VM Service have an <code>id</code> property. An id is used to request an object from the VM.
+Most responses returned by the VM Service have an <code>id</code>
+property. An id is used to request an object from the VM. Each id is
+unique; that is to say, If two responses have the same id, they refer
+to the same object. The converse is not true: the same object may
+occasionally be returned with two different ids.
-An id is either _global_ or _relative_. Global ids can be requested from the VM directly by requesting the uri <code>/{global id}</code>.
+An id is either _global_ or _relative_. Global ids can be requested
+from the VM directly by requesting the uri <code>/{global id}</code>.
The following is a list of known, fixed global ids:
@@ -44,89 +61,60 @@ The following is a list of known, fixed global ids:
| vm | /vm | [VM](#VM)
| flags | /flags | [FlagList](#FlagList)
-In addition, all isolates have global ids, but these ids are dynamically generated. An isolate with an id like <code>isolates/123</code> would be available at the uri <code>/isolates/123</code>.
+In addition, all isolates have global ids, but these ids are
+dynamically generated. An isolate with an id like
+<code>isolates/123</code> would be available at the uri
+<code>/isolates/123</code>.
-Relative ids are used to refer to objects that are owned by an isolate. Relative ids can be requested from the VM directly by requesting the uri <code>/{isolate&nbsp;id}/{relative&nbsp;id}</code>.
+Relative ids are used to refer to objects that are owned by an
+isolate. Relative ids can be requested from the VM directly by
+requesting the uri <code>/{isolate&nbsp;id}/{relative&nbsp;id}</code>.
-For example, we can get information about a class with id <code>classes/Foo</code> from isolate <code>isolates/123</code> by requesting the uri <code>/isolates/123/classes/Foo</code> from the VM.
+For example, we can get information about a class with id
+<code>classes/Foo</code> from isolate <code>isolates/123</code> by
+requesting the uri <code>/isolates/123/classes/Foo</code> from the VM.
-The client must not parse ids -- they must be treated as opaque strings. We reserve the right to change the ids of objects.
+The client must not parse ids -- they must be treated as opaque
+strings. We reserve the right to change the ids of objects.
-## Events
+## Names
-TODO
+Many responses have the <code>name</code> property. Names are
+provided so that objects can be displayed in a way that a Dart
+language programmer would find sensible.
-## Catalog of Types
-### <a name="VM"></a>VM
+Note that names are not in any way unique. Many objects will have the
+same name.
-| keys | values | comments
-| --- | --- | ---
-| type | "VM" |
-| id | String |
-| targetCPU | String |
-| hostCPU | String |
-| date | String | kill? |
-| version | String |
-| pid | int |
-| assertsEnabled | bool | TODO: move to features? |
-| typeChecksEnabled | bool | TODO: move to features? |
-| uptime | double | seconds since vm started |
-| "isolates" | List of [@Isolate](#atIsolate) |
+Occasionally responses will have the <code>vmName</code> property.
+This represents the internal names used to refer to an object inside
+the VM itself. The <code>vmName</code> of an object is only provided
+when it differs from the <code>name</code> property; when
+<code>vmName</code> is not present, the client may assume the
+<code>name</code> and <code>vmName</code> are the same.
-### <a name="atIsolate"></a>@Isolate
+## Events
-| keys | values | comments
-| --- | --- | ---
-| type | "@Isolate" |
-| id | String |
-| mainPort | String | kill? |
-| name | String |
+TODO
-### Isolate
+## Catalog of Types
-| keys | values | comments
-| --- | --- | ---
-| type | "Isolate" |
-| id | String |
-| mainPort | String | kill? |
-| name | String |
-| entry? | [@Function](#atFunction) |
-| heaps | ??? |
-| topFrame? | [Frame](#Frame) |
-| livePorts | int |
-| pauseOnExit | bool |
-| pauseEvent? | [DebuggerEvent](#DebuggerEvent) |
-| rootLib | [@Library](#atLibrary) |
-| timers | ??? |
-| tagCounters | ??? |
-| error? | [Error](#Error) |
-| canonicalTypeArguments | | kill? |
-| libs | List of [@Library](#atLibrary) |
-| features | List of String |
+### <a name="atAbstractType"></a>@AbstractType
-### <a name="atLibrary"></a>@Library
+### <a name="AbstractType"></a>AbstractType
-| keys | values | comments
-| --- | --- | ---
-| type | "@Library" |
-| id | String |
-| name | String |
-| vmName? | String | Internal vm name. Provided only when different from 'name'.
-| url | String
+### <a name="Breakpoint"></a>Breakpoint
-### <a name="Library"></a>Library
+TODO: Get rid of Location or else use it more generally.
| keys | values | comments
| --- | --- | ---
-| type | "Library" |
+| type | "Breakpoint" |
| id | String |
-| name | String |
-| vmName? | String | Internal vm name. Provided only when different from 'name'.
-| classes | List of [@Class](#atClass) |
-| imports | List of [@Library](#atLibrary) |
-| variables | List of ... |
-| functions | List of [@Function](#atFunction) |
-| scripts | List of [@Script](#atScript) |
+| breakpointNumber | int |
+| enabled | bool |
+| resolved | bool |
+| location | [Location](#Location) |
### <a name="atClass"></a>@Class
| keys | values | comments
@@ -161,41 +149,90 @@ TODO
| canonicalTypes | [@TypeList] | kill?
| allocationStats | ClassHeapStats |
-### <a name="atFunction"></a>@Function
+### <a name="ClassHeapStats"></a>ClassHeapStats
| keys | values | comments
| --- | --- | ---
-| type | "@Function" |
+| type | "ClassHeapStats" |
+| id | String |
+| class | [@Class](#atClass) |
+| new | List of int | Allocation statistics for new space. See note below on allocation statistics list format.
+| old | List of int | Allocation statistics for old space. See note below on allocation statistics list format.
+| promotedInstances | int | number of instances promoted at last new-space GC.
+| promotedBytes | int | number of bytes promoted at last new-space GC.
+
+*Allocation statistics list format*
+| index | value | description
+| --- | --- | --- |
+| 0 | int | Instances allocated before last GC |
+| 1 | int | Bytes allocated before last GC |
+| 2 | int | Instances alive after last GC |
+| 3 | int | Bytes alive after last GC |
+| 4 | int | Instances allocated since last GC |
+| 5 | int | Bytes allocated since last GC |
+| 6 | int | Instances allocated since last accumulator reset |
+| 7 | int | Bytes allocated since last accumulator reset |
+
+### <a name="atCode"></a>@Code
+| keys | values | comments
+| --- | --- | ---
+| type | "@Code" |
| id | String |
| user_name | String |
| name | String |
-| owningLibrary? | [@Library](#atLibrary) | Set for non-top level functions
-| owningClass? | [@Class](#atClass) | Set for non-top level functions
-| parent? | [@Function](#atFunction) | Parent function
-| kind | String |
+| start | String | starting address of code
+| end | String | ending address of code
+| isOptimized | bool |
+| isAlive | bool |
+| kind | String
+| function | [@Function](#atFunction) |
-### <a name="Function"></a>Function
+### <a name="Code"></a>Code
| keys | values | comments
| --- | --- | ---
-| type | "@Function" |
+| type | "@Code" |
| id | String |
| user_name | String |
| name | String |
-| owningLibrary | [@Library](#atLibrary) | Set for non-top level functions
-| owningClass | [@Class](#atClass) | Set for non-top level functions
-| parent? | [@Function](#atFunction) | Parent function
+| start | String | starting address of code
+| end | String | ending address of code
+| isOptimized | bool |
+| isAlive | bool |
+| kind | String
+| function | [@Function](#atFunction) |
+| object_pool | List of [@Object](Object) |
+| disassembly | List of String | See note below on disassembly list format
+
+*Disassembly list format*
+| index | value | description
+| --- | --- | --- |
+| 0 | String | Address of instruction
+| 1 | String | Hex encoding of instruction
+| 2 | String | Human encoding of instruction
+| 0 + (3 * K) | String | Address of Kth instruction
+| 1 + (3 * K) | String | Hex encoding of instruction of Kth instruction
+| 2 + (3 * K) | String | Human encoding of instruction of Kth instruction
+
+### <a name="DebuggerEvent"></a>DebuggerEvent
+
+| keys | values | comments
+| --- | --- | ---
+| type | "DebuggerEvent" |
+| id | String | TODO: Remove |
+| eventType | String | "BreakpointReached", "BreakpointResolved", "ExceptionThrown", "IsolateCreated", "IsolateShutdown", or "IsolateInterrupted" |
+| isolate | [@Isolate](#atIsolate) |
+| breakpoint? | [Breakpoint](#atBreakpoint) | for eventTypes "BreakpointResolved" and "BreakpointReached<br><br>TODO: Maybe make this @Breakpoint?
+| exception? | [@Instance](#atInstance) | for eventType "ExceptionThrown"
+
+### <a name="Error"></a>Error
+
+TODO: Drop id from Error.
+
+| keys | values | comments
+| --- | --- | ---
+| type | "Error" |
+| id | String | always empty
| kind | String |
-| is_static | bool |
-| is_const | bool |
-| is_optimizable | bool |
-| is_inlinable | bool |
-| usage_counter | int |
-| optimized_call_site_count | int |
-| deoptimizations | int |
-| script? | [@Script](#atScript) | Script containing function source
-| tokenPos? | int | starting token position of function source in script
-| endTokenPos? | int | end token position of function source in script
-| unoptimized_code | [@Code](#atCode) |
-| code | [@Code](#atCode) | Current code
+| message | String |
### <a name="atField"></a>@Field
| keys | values | comments
@@ -231,83 +268,135 @@ TODO
| script? | [@Script](#atScript) | Script containing field source
| tokenPos? | int | starting token position of field source in script
-### <a name="atCode"></a>@Code
+### <a name="Frame"></a>Frame
+
+TODO: Add type and id?<br>
+
| keys | values | comments
| --- | --- | ---
-| type | "@Code" |
+| script | [@Script](#atScript) |
+| tokenPos | int |
+| function | [@Function](#atFunction) |
+| code | [@Code](#atCode) |
+| vars | List of [FrameVar](#FrameVar) |
+
+### <a name="FrameVar"></a>FrameVar
+
+| keys | values | comments
+| --- | --- | ---
+| name | String |
+| value | [@Instance](#atInstance) |
+
+### <a name="atFunction"></a>@Function
+| keys | values | comments
+| --- | --- | ---
+| type | "@Function" |
| id | String |
| user_name | String |
| name | String |
-| start | String | starting address of code
-| end | String | ending address of code
-| isOptimized | bool |
-| isAlive | bool |
-| kind | String
-| function | [@Function](#atFunction) |
+| owningLibrary? | [@Library](#atLibrary) | Set for non-top level functions
+| owningClass? | [@Class](#atClass) | Set for non-top level functions
+| parent? | [@Function](#atFunction) | Parent function
+| kind | String |
-### <a name="Code"></a>Code
+### <a name="Function"></a>Function
| keys | values | comments
| --- | --- | ---
-| type | "@Code" |
+| type | "@Function" |
| id | String |
| user_name | String |
| name | String |
-| start | String | starting address of code
-| end | String | ending address of code
-| isOptimized | bool |
-| isAlive | bool |
-| kind | String
-| function | [@Function](#atFunction) |
-| object_pool | List of [@Object](Object) |
-| disassembly | List of String | See note below on disassembly list format
+| owningLibrary | [@Library](#atLibrary) | Set for non-top level functions
+| owningClass | [@Class](#atClass) | Set for non-top level functions
+| parent? | [@Function](#atFunction) | Parent function
+| kind | String |
+| is_static | bool |
+| is_const | bool |
+| is_optimizable | bool |
+| is_inlinable | bool |
+| usage_counter | int |
+| optimized_call_site_count | int |
+| deoptimizations | int |
+| script? | [@Script](#atScript) | Script containing function source
+| tokenPos? | int | starting token position of function source in script
+| endTokenPos? | int | end token position of function source in script
+| unoptimized_code | [@Code](#atCode) |
+| code | [@Code](#atCode) | Current code
-*Disassembly list format*
-| index | value | description
-| --- | --- | --- |
-| 0 | String | Address of instruction
-| 1 | String | Hex encoding of instruction
-| 2 | String | Human encoding of instruction
-| 0 + (3 * K) | String | Address of Kth instruction
-| 1 + (3 * K) | String | Hex encoding of instruction of Kth instruction
-| 2 + (3 * K) | String | Human encoding of instruction of Kth instruction
+### <a name="atIsolate"></a>@Isolate
-### <a name="Error"></a>Error
| keys | values | comments
| --- | --- | ---
-| type | "Error" |
-| id | String | always empty
-| kind | String |
-| message | String |
+| type | "@Isolate" |
+| id | String |
+| mainPort | String | kill? |
+| name | String |
+
+### Isolate
-### <a name="ClassHeapStats"></a>ClassHeapStats
| keys | values | comments
| --- | --- | ---
-| type | "ClassHeapStats" |
+| type | "Isolate" |
| id | String |
-| class | [@Class](#atClass) |
-| new | List of int | Allocation statistics for new space. See note below on allocation statistics list format.
-| old | List of int | Allocation statistics for old space. See note below on allocation statistics list format.
-| promotedInstances | int | number of instances promoted at last new-space GC.
-| promotedBytes | int | number of bytes promoted at last new-space GC.
+| mainPort | String | kill? |
+| name | String |
+| entry? | [@Function](#atFunction) |
+| heaps | ??? |
+| topFrame? | [Frame](#Frame) |
+| livePorts | int |
+| pauseOnExit | bool |
+| pauseEvent? | [DebuggerEvent](#DebuggerEvent) |
+| rootLib | [@Library](#atLibrary) |
+| timers | ??? |
+| tagCounters | ??? |
+| error? | [Error](#Error) |
+| canonicalTypeArguments | | kill? |
+| libs | List of [@Library](#atLibrary) |
+| features | List of String |
-*Allocation statistics list format*
-| index | value | description
-| --- | --- | --- |
-| 0 | int | Instances allocated before last GC |
-| 1 | int | Bytes allocated before last GC |
-| 2 | int | Instances alive after last GC |
-| 3 | int | Bytes alive after last GC |
-| 4 | int | Instances allocated since last GC |
-| 5 | int | Bytes allocated since last GC |
-| 6 | int | Instances allocated since last accumulator reset |
-| 7 | int | Bytes allocated since last accumulator reset |
+### <a name="atLibrary"></a>@Library
-### <a name="atAbstractType"></a>@AbstractType
+| keys | values | comments
+| --- | --- | ---
+| type | "@Library" |
+| id | String |
+| name | String |
+| vmName? | String | Internal vm name. Provided only when different from 'name'.
+| url | String
-### <a name="AbstractType"></a>AbstractType
+### <a name="Library"></a>Library
-### <a name="PcDescriptor"></a>PcDescriptor
+| keys | values | comments
+| --- | --- | ---
+| type | "Library" |
+| id | String |
+| name | String |
+| vmName? | String | Internal vm name. Provided only when different from 'name'.
+| classes | List of [@Class](#atClass) |
+| imports | List of [@Library](#atLibrary) |
+| variables | List of ... |
+| functions | List of [@Function](#atFunction) |
+| scripts | List of [@Script](#atScript) |
+
+### <a name="Location"></a>Location
+
+| keys | values | comments
+| --- | --- | ---
+| type | "Location" |
+| script | [@Script](#atScript) |
+| tokenPos | int |
+
+### <a name="@Null"></a>@Null
+
+TODO: Split Null from the other Sentinel types.
+| keys | values | comments
+| --- | --- | ---
+| type | "@Null" |
+| id | String | |
+| valueAsString | String |
+
+### <a name="PcDescriptor"></a>PcDescriptor
### <a name="atScript"></a>@Script
| keys | values | comments | example |
@@ -339,3 +428,20 @@ TODO
| ... | ... | ...
| 1 + (2 * k) | int | kth token position
| 2 + (2 * k) | int | kth column number
+
+### <a name="VM"></a>VM
+
+| keys | values | comments
+| --- | --- | ---
+| type | "VM" |
+| id | String |
+| targetCPU | String |
+| hostCPU | String |
+| date | String | kill? |
+| version | String |
+| pid | int |
+| assertsEnabled | bool | TODO: move to features? |
+| typeChecksEnabled | bool | TODO: move to features? |
+| uptime | double | seconds since vm started |
+| "isolates" | List of [@Isolate](#atIsolate) |
+
« no previous file with comments | « no previous file | no next file » | no next file with comments »

Powered by Google App Engine
This is Rietveld 408576698