OLD | NEW |
1 # Dart VM Service Protocol | 1 # Dart VM Service Protocol |
2 | 2 |
3 NOTE: The service api is still changing rapidly. If you use the | 3 NOTE: The service api is still changing rapidly. If you use the |
4 service api, expect to encounter non-compatible changes. | 4 service api, expect to encounter non-compatible changes. |
5 | 5 |
6 Description | 6 Description |
7 How to start | 7 How to start |
8 JSON | 8 JSON |
9 Websocket | 9 Websocket |
10 | 10 |
(...skipping 25 matching lines...) Expand all Loading... |
36 { | 36 { |
37 type: "Isolate", | 37 type: "Isolate", |
38 id: "isolates/123", | 38 id: "isolates/123", |
39 name: "worker" | 39 name: "worker" |
40 entry: ... | 40 entry: ... |
41 heaps: ... | 41 heaps: ... |
42 topFrame: ... | 42 topFrame: ... |
43 ... | 43 ... |
44 } | 44 } |
45 | 45 |
| 46 ## Type Hierarchy |
| 47 |
| 48 The types returned by the VM Service fit into a type hierarchy, with a |
| 49 subtyping relationship as indicated by the following indented list: |
| 50 |
| 51 <pre> |
| 52 Object |
| 53 ClassHeapStats |
| 54 Class |
| 55 Code |
| 56 Context |
| 57 Counter |
| 58 Error |
| 59 Field |
| 60 FrameVar |
| 61 Frame |
| 62 Function |
| 63 Gauge |
| 64 Instance |
| 65 AbstractType |
| 66 BoundedType |
| 67 TypeParameter |
| 68 TypeRef |
| 69 Type |
| 70 List |
| 71 Sentinel // TODO - subtype of Instance or not? |
| 72 String |
| 73 bool |
| 74 double |
| 75 int |
| 76 null |
| 77 Isolate |
| 78 Library |
| 79 Location |
| 80 Script |
| 81 ServiceError |
| 82 ServiceEvent |
| 83 Socket |
| 84 TypeArguments // TODO - expose? |
| 85 VM |
| 86 </pre> |
| 87 |
| 88 TODO: How to put links in a pre in markdown? |
| 89 |
| 90 A subtype is guaranteed to provide all of the properties of its |
| 91 parent type. For example, an [int](#int) can be used as an |
| 92 [Instance](#Instance). |
| 93 |
| 94 The subtyping relationship also holds for reference types. For |
| 95 example, [@int](#int) can be used as an [@Instance](#Instance). |
| 96 |
46 ## IDs | 97 ## IDs |
47 | 98 |
48 Most responses returned by the VM Service have an <code>id</code> | 99 Most responses returned by the VM Service have an <code>id</code> |
49 property. An id is used to request an object from the VM. Each id is | 100 property. An id is used to request an object from the VM. Each id is |
50 unique; that is to say, If two responses have the same id, they refer | 101 unique; that is to say, If two responses have the same id, they refer |
51 to the same object. The converse is not true: the same object may | 102 to the same object. The converse is not true: the same object may |
52 occasionally be returned with two different ids. | 103 occasionally be returned with two different ids. |
53 | 104 |
54 An id is either _global_ or _relative_. Global ids can be requested | 105 An id is either _global_ or _relative_. Global ids can be requested |
55 from the VM directly by requesting the uri <code>/{global id}</code>. | 106 from the VM directly by requesting the uri <code>/{global id}</code>. |
(...skipping 23 matching lines...) Expand all Loading... |
79 | 130 |
80 ## Names | 131 ## Names |
81 | 132 |
82 Many responses have the <code>name</code> property. Names are | 133 Many responses have the <code>name</code> property. Names are |
83 provided so that objects can be displayed in a way that a Dart | 134 provided so that objects can be displayed in a way that a Dart |
84 language programmer would find sensible. | 135 language programmer would find sensible. |
85 | 136 |
86 Note that names are not in any way unique. Many objects will have the | 137 Note that names are not in any way unique. Many objects will have the |
87 same name. | 138 same name. |
88 | 139 |
89 Occasionally responses will have the <code>vmName</code> property. | 140 ## Private Properties |
90 This represents the internal names used to refer to an object inside | 141 |
91 the VM itself. The <code>vmName</code> of an object is only provided | 142 Some properties returned by the VM Service begin with an underscore |
92 when it differs from the <code>name</code> property; when | 143 (<code>_</code>) character. These properties are called _private |
93 <code>vmName</code> is not present, the client may assume the | 144 properties_. Private properties provide private information about the |
94 <code>name</code> and <code>vmName</code> are the same. | 145 VM's implementation. Private properties may be added, removed, or |
| 146 changed at any time with any release of the VM. They are provided for |
| 147 those tools that need this level of internal access, such as the |
| 148 Observatory. |
| 149 |
| 150 For example, some responses will have the <code>_vmType</code> |
| 151 nnnproperty. This provides the VM-internal type name of an object, and |
| 152 is provided only when this type name differs from the |
| 153 <code>type</code> property. |
95 | 154 |
96 ## Events | 155 ## Events |
97 | 156 |
98 TODO | 157 TODO |
99 | 158 |
100 ## Catalog of Types | 159 ## Catalog of Types |
101 | 160 |
102 ### <a name="AbstractType"></a>AbstractType | 161 ### <a name="AbstractType"></a>AbstractType |
103 | 162 |
104 ### <a name="Breakpoint"></a>Breakpoint | 163 ### <a name="Breakpoint"></a>Breakpoint |
(...skipping 13 matching lines...) Expand all Loading... |
118 | 177 |
119 ### <a name="Class"></a>Class | 178 ### <a name="Class"></a>Class |
120 | 179 |
121 Reference properties: | 180 Reference properties: |
122 | 181 |
123 | keys | values | comments | 182 | keys | values | comments |
124 | --- | --- | --- | 183 | --- | --- | --- |
125 | type | "@Class", "Class" | | 184 | type | "@Class", "Class" | |
126 | id | String | | 185 | id | String | |
127 | name | String | | 186 | name | String | |
128 | vmName? | String | | 187 | _vmName? | String | |
129 | 188 |
130 Object properties: | 189 Object properties: |
131 | 190 |
132 | keys | values | comments | 191 | keys | values | comments |
133 | --- | --- | --- | 192 | --- | --- | --- |
134 | error? | [Error](#Error) | Error encountered during class finalization | 193 | error? | [Error](#Error) | Error encountered during class finalization |
135 | implemented | bool | | 194 | implemented | bool | |
136 | abstract | bool | | 195 | abstract | bool | |
137 | patch | bool | | 196 | patch | bool | |
138 | finalized | bool | | 197 | finalized | bool | |
(...skipping 39 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
178 | 237 |
179 ### <a name="Code"></a>Code | 238 ### <a name="Code"></a>Code |
180 | 239 |
181 Reference properties: | 240 Reference properties: |
182 | 241 |
183 | keys | values | comments | 242 | keys | values | comments |
184 | --- | --- | --- | 243 | --- | --- | --- |
185 | type | "@Code", "Code"| | 244 | type | "@Code", "Code"| |
186 | id | String | | 245 | id | String | |
187 | name | String | | 246 | name | String | |
188 | vmName? | String | | 247 | _vmName? | String | |
189 | start | String | starting address of code | 248 | start | String | starting address of code |
190 | end | String | ending address of code | 249 | end | String | ending address of code |
191 | isOptimized | bool | | 250 | isOptimized | bool | |
192 | isAlive | bool | | 251 | isAlive | bool | |
193 | kind | String | 252 | kind | String |
194 | function | [@Function](#Function) | | 253 | function | [@Function](#Function) | |
195 | 254 |
196 Object properties: | 255 Object properties: |
197 | 256 |
198 | keys | values | comments | 257 | keys | values | comments |
(...skipping 11 matching lines...) Expand all Loading... |
210 | 269 |
211 | index | value | description | 270 | index | value | description |
212 | --- | --- | --- | | 271 | --- | --- | --- | |
213 | 0 | String | Address of instruction | 272 | 0 | String | Address of instruction |
214 | 1 | String | Hex encoding of instruction | 273 | 1 | String | Hex encoding of instruction |
215 | 2 | String | Human encoding of instruction | 274 | 2 | String | Human encoding of instruction |
216 | 0 + (3 * K) | String | Address of Kth instruction | 275 | 0 + (3 * K) | String | Address of Kth instruction |
217 | 1 + (3 * K) | String | Hex encoding of instruction of Kth instruction | 276 | 1 + (3 * K) | String | Hex encoding of instruction of Kth instruction |
218 | 2 + (3 * K) | String | Human encoding of instruction of Kth instruction | 277 | 2 + (3 * K) | String | Human encoding of instruction of Kth instruction |
219 | 278 |
220 ### <a name="DebuggerEvent"></a>DebuggerEvent | |
221 | |
222 Object properties: | |
223 | |
224 | keys | values | comments | |
225 | --- | --- | --- | |
226 | type | "DebuggerEvent" | | |
227 | id | String | TODO: Remove | | |
228 | eventType | String | "BreakpointReached", "BreakpointResolved", "ExceptionThro
wn", "IsolateCreated", "IsolateShutdown", "IsolateInterrupted" | | |
229 | isolate | [@Isolate](#Isolate) | | |
230 | breakpoint? | [Breakpoint](#Breakpoint) | for eventTypes "BreakpointResolved"
and "BreakpointReached<br><br>TODO: Maybe make this @Breakpoint? | |
231 | exception? | [@Instance](#Instance) | for eventType "ExceptionThrown" | |
232 | |
233 ### <a name="Error"></a>Error | 279 ### <a name="Error"></a>Error |
234 | 280 |
235 TODO: Drop id from Error.<br> | 281 TODO: Drop id from Error.<br> |
236 | 282 |
237 Object properties: | 283 Object properties: |
238 | 284 |
239 | keys | values | comments | 285 | keys | values | comments |
240 | --- | --- | --- | 286 | --- | --- | --- |
241 | type | "Error" | | 287 | type | "Error" | |
| 288 | _vmType? | String | VM internal name for this type. Provided only when differ
ent from 'type' |
242 | id | String | always empty | 289 | id | String | always empty |
243 | kind | String | | 290 | kind | String | |
244 | message | String | | 291 | message | String | |
245 | 292 |
246 ### <a name="Field"></a>Field | 293 ### <a name="Field"></a>Field |
247 | 294 |
248 Reference properties: | 295 Reference properties: |
249 | 296 |
250 | keys | values | comments | 297 | keys | values | comments |
251 | --- | --- | --- | 298 | --- | --- | --- |
252 | type | "@Field", "Field" | | 299 | type | "@Field", "Field" | |
253 | id | String | | 300 | id | String | |
254 | name | String | | 301 | name | String | |
255 | vmName? | String | | 302 | _vmName? | String | |
256 | value? | Instance | value associated with static field <-- do we want to inclu
de this in a field reference? | 303 | value? | Instance | value associated with static field <-- do we want to inclu
de this in a field reference? |
257 | owner | [@Library](#Library),[@Class](#Class) | Owning library or class <-- ha
ndling of owner is inconsistent with Function | 304 | owner | [@Library](#Library),[@Class](#Class) | Owning library or class <-- ha
ndling of owner is inconsistent with Function |
258 | declared_type | [@AbstractType](#AbstractType) | | 305 | declared_type | [@AbstractType](#AbstractType) | |
259 | static | bool | | 306 | static | bool | |
260 | final | bool | | 307 | final | bool | |
261 | const | bool | | 308 | const | bool | |
262 | 309 |
263 Object properties: | 310 Object properties: |
264 | 311 |
265 | keys | values | comments | 312 | keys | values | comments |
(...skipping 29 matching lines...) Expand all Loading... |
295 | 342 |
296 ### <a name="Function"></a>Function | 343 ### <a name="Function"></a>Function |
297 | 344 |
298 Reference properties: | 345 Reference properties: |
299 | 346 |
300 | keys | values | comments | 347 | keys | values | comments |
301 | --- | --- | --- | 348 | --- | --- | --- |
302 | type | "@Function", "Function" | | 349 | type | "@Function", "Function" | |
303 | id | String | | 350 | id | String | |
304 | name | String | | 351 | name | String | |
305 | vmName? | String | | 352 | _vmName? | String | |
306 | owningLibrary? | [@Library](#Library) | Set for non-top level functions | 353 | owningLibrary? | [@Library](#Library) | Set for non-top level functions |
307 | owningClass? | [@Class](#Class) | Set for non-top level functions | 354 | owningClass? | [@Class](#Class) | Set for non-top level functions |
308 | parent? | [@Function](#Function) | Parent function | 355 | parent? | [@Function](#Function) | Parent function |
309 | kind | String | | 356 | kind | String | |
310 | 357 |
311 Object properties: | 358 Object properties: |
312 | 359 |
313 | keys | values | comments | 360 | keys | values | comments |
314 | --- | --- | --- | 361 | --- | --- | --- |
315 | static | bool | TODO: not consistent with Field | 362 | static | bool | TODO: not consistent with Field |
(...skipping 40 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
356 | 403 |
357 ### <a name="Library"></a>Library | 404 ### <a name="Library"></a>Library |
358 | 405 |
359 Reference properties: | 406 Reference properties: |
360 | 407 |
361 | keys | values | comments | 408 | keys | values | comments |
362 | --- | --- | --- | 409 | --- | --- | --- |
363 | type | "@Library", "Library" | | 410 | type | "@Library", "Library" | |
364 | id | String | | 411 | id | String | |
365 | name | String | | 412 | name | String | |
366 | vmName? | String | Internal vm name. Provided only when different from 'name'
. | 413 | _vmName? | String | VM-internal name. Provided only when different from 'name
'. |
367 | url | String | 414 | url | String |
368 | 415 |
369 Object properties: | 416 Object properties: |
370 | 417 |
371 | keys | values | comments | 418 | keys | values | comments |
372 | --- | --- | --- | 419 | --- | --- | --- |
373 | classes | List of [@Class](#Class) | | 420 | classes | List of [@Class](#Class) | |
374 | imports | List of [@Library](#Library) | | 421 | imports | List of [@Library](#Library) | |
375 | variables | List of ... | | 422 | variables | List of ... | |
376 | functions | List of [@Function](#Function) | | 423 | functions | List of [@Function](#Function) | |
377 | scripts | List of [@Script](#Script) | | 424 | scripts | List of [@Script](#Script) | |
378 | 425 |
379 ### <a name="Location"></a>Location | 426 ### <a name="Location"></a>Location |
380 | 427 |
381 Object properties: | 428 Object properties: |
382 | 429 |
383 | keys | values | comments | 430 | keys | values | comments |
384 | --- | --- | --- | 431 | --- | --- | --- |
385 | type | "Location" | | 432 | type | "Location" | |
386 | script | [@Script](#Script) | | 433 | script | [@Script](#Script) | |
387 | tokenPos | int | | 434 | tokenPos | int | |
388 | 435 |
389 ### <a name="Null"></a>Null | 436 ### <a name="null"></a>null |
390 | 437 |
391 Reference properties: | 438 Reference properties: |
392 | 439 |
393 | keys | values | comments | 440 | keys | values | comments |
394 | --- | --- | --- | 441 | --- | --- | --- |
395 | type | "@Null", "Null" | | 442 | type | "@null", "null" | |
396 | id | String | | | 443 | id | String | | |
397 | valueAsString | String | | 444 | valueAsString | String | |
398 | 445 |
399 Object properties:<br> | 446 Object properties:<br> |
400 | 447 |
401 TODO. | 448 TODO. |
402 | 449 |
| 450 ### <a name="Object"></a>Object |
| 451 |
| 452 [Object](#Object) is the supertype of all responses returned by the VM |
| 453 Service. It does not necessarily refer to an Object at the Dart |
| 454 language level (see [Instance](#Instance)). |
| 455 |
| 456 Reference properties: |
| 457 |
| 458 | keys | values | comments |
| 459 | --- | --- | --- |
| 460 | type | "@Object", "Object" or subtype | |
| 461 | _vmType? | String | VM internal name for this type. Provided only when differ
ent from 'type' |
| 462 | id | String | |
| 463 |
| 464 Object properties: none<br> |
| 465 |
403 ### <a name="PcDescriptor"></a>PcDescriptor | 466 ### <a name="PcDescriptor"></a>PcDescriptor |
404 | 467 |
405 ### <a name="Script"></a>Script | 468 ### <a name="Script"></a>Script |
406 | 469 |
407 Reference properties: | 470 Reference properties: |
408 | 471 |
409 | keys | values | comments | example | | 472 | keys | values | comments | example | |
410 | --- | --- | --- | 473 | --- | --- | --- |
411 | type | "@Script", "Script" | | 474 | type | "@Script", "Script" | |
412 | id | String | 475 | id | String |
413 | name | String | 476 | name | String |
414 | vmName? | String | Internal vm name. Provided only when different from 'name'
. | 477 | _vmName? | String | VM-internal name. Provided only when different from 'name
'. |
415 | kind | String | 478 | kind | String |
416 | 479 |
417 Object properties: | 480 Object properties: |
418 | 481 |
419 | keys | values | comments | 482 | keys | values | comments |
420 | --- | --- | --- | 483 | --- | --- | --- |
421 | owningLibrary | [@Library](#Library) | 484 | owningLibrary | [@Library](#Library) |
422 | source | String | 485 | source | String |
423 | tokenPosTable | List of list of int. See note below about token line format. | 486 | tokenPosTable | List of list of int. See note below about token line format. |
424 | 487 |
(...skipping 14 matching lines...) Expand all Loading... |
439 TODO: Should this even have an id? Maybe a *kind* instead.<br><br> | 502 TODO: Should this even have an id? Maybe a *kind* instead.<br><br> |
440 | 503 |
441 Object properties: | 504 Object properties: |
442 | 505 |
443 | keys | values | comments | 506 | keys | values | comments |
444 | --- | --- | --- | 507 | --- | --- | --- |
445 | type | "Sentinel" | | 508 | type | "Sentinel" | |
446 | id | String | | | 509 | id | String | | |
447 | valueAsString | String | | 510 | valueAsString | String | |
448 | 511 |
| 512 ### <a name="ServiceEvent"></a>ServiceEvent |
| 513 |
| 514 Object properties: |
| 515 |
| 516 | keys | values | comments |
| 517 | --- | --- | --- |
| 518 | type | "ServiceEvent" | |
| 519 | id | String | TODO: Remove | |
| 520 | eventType | String | "BreakpointReached", "BreakpointResolved", "ExceptionThro
wn", "IsolateCreated", "IsolateShutdown", "IsolateInterrupted" | |
| 521 | isolate | [@Isolate](#Isolate) | |
| 522 | breakpoint? | [Breakpoint](#Breakpoint) | for eventTypes "BreakpointResolved"
and "BreakpointReached<br><br>TODO: Maybe make this @Breakpoint? |
| 523 | exception? | [@Instance](#Instance) | for eventType "ExceptionThrown" |
| 524 |
449 ### <a name="VM"></a>VM | 525 ### <a name="VM"></a>VM |
450 | 526 |
451 Object properties: | 527 Object properties: |
452 | 528 |
453 | keys | values | comments | 529 | keys | values | comments |
454 | --- | --- | --- | 530 | --- | --- | --- |
455 | type | "VM" | | 531 | type | "VM" | |
456 | id | String | | 532 | id | String | |
457 | targetCPU | String | | 533 | targetCPU | String | |
458 | hostCPU | String | | 534 | hostCPU | String | |
459 | date | String | kill? | | 535 | date | String | kill? | |
460 | version | String | | 536 | version | String | |
461 | pid | int | | 537 | pid | int | |
462 | assertsEnabled | bool | TODO: move to features? | | 538 | assertsEnabled | bool | TODO: move to features? | |
463 | typeChecksEnabled | bool | TODO: move to features? | | 539 | typeChecksEnabled | bool | TODO: move to features? | |
464 | uptime | double | seconds since vm started | | 540 | uptime | double | seconds since vm started | |
465 | "isolates" | List of [@Isolate](#Isolate) | | 541 | "isolates" | List of [@Isolate](#Isolate) | |
466 | 542 |
OLD | NEW |