| OLD | NEW |
| 1 # Dart VM Service Protocol 0.0 | 1 # Dart VM Service Protocol 0.0 |
| 2 | 2 |
| 3 This document describes _version 0.0_ of the Dart VM Service Protocol. | 3 This document describes _version 0.0_ of the Dart VM Service Protocol. |
| 4 This protocol is used to communicate with a running Dart Virtual | 4 This protocol is used to communicate with a running Dart Virtual |
| 5 Machine. | 5 Machine. |
| 6 | 6 |
| 7 To use the Service Protocol, start the VM with the *--observe* flag. | 7 To use the Service Protocol, start the VM with the *--observe* flag. |
| 8 The VM will start a webserver which services protocol requests via WebSocket. | 8 The VM will start a webserver which services protocol requests via WebSocket. |
| 9 It is possible to make HTTP (non-WebSocket) requests, | 9 It is possible to make HTTP (non-WebSocket) requests, |
| 10 but this does not allow access to VM _events_ and is not documented | 10 but this does not allow access to VM _events_ and is not documented |
| (...skipping 34 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 45 - [BoundField](#boundfield) | 45 - [BoundField](#boundfield) |
| 46 - [BoundVariable](#boundvariable) | 46 - [BoundVariable](#boundvariable) |
| 47 - [Breakpoint](#breakpoint) | 47 - [Breakpoint](#breakpoint) |
| 48 - [Class](#class) | 48 - [Class](#class) |
| 49 - [ClassList](#classlist) | 49 - [ClassList](#classlist) |
| 50 - [Code](#code) | 50 - [Code](#code) |
| 51 - [CodeKind](#codekind) | 51 - [CodeKind](#codekind) |
| 52 - [Double](#double) | 52 - [Double](#double) |
| 53 - [Error](#error) | 53 - [Error](#error) |
| 54 - [Event](#event) | 54 - [Event](#event) |
| 55 » - [EventType](#eventtype) | 55 » - [EventKind](#eventkind) |
| 56 - [Field](#field) | 56 - [Field](#field) |
| 57 - [Flag](#flag) | 57 - [Flag](#flag) |
| 58 - [FlagList](#flaglist) | 58 - [FlagList](#flaglist) |
| 59 - [Frame](#frame) | 59 - [Frame](#frame) |
| 60 - [Function](#function) | 60 - [Function](#function) |
| 61 - [Instance](#instance) | 61 - [Instance](#instance) |
| 62 - [Int](#int) | 62 - [Int](#int) |
| 63 - [Isolate](#isolate) | 63 - [Isolate](#isolate) |
| 64 - [Library](#library) | 64 - [Library](#library) |
| 65 - [List](#list) | 65 - [List](#list) |
| 66 - [ListElement](#listelement) | 66 - [ListElement](#listelement) |
| 67 - [Message](#message) | 67 - [Message](#message) |
| 68 - [Null](#null) | 68 - [Null](#null) |
| 69 - [Object](#object) | 69 - [Object](#object) |
| 70 - [Sentinel](#sentinel) | 70 - [Sentinel](#sentinel) |
| 71 » - [SentinelType](#sentineltype) | 71 » - [SentinelKind](#sentinelkind) |
| 72 - [Script](#script) | 72 - [Script](#script) |
| 73 - [Stack](#stack) | 73 - [Stack](#stack) |
| 74 - [StepOption](#stepoption) | 74 - [StepOption](#stepoption) |
| 75 - [String](#string) | 75 - [String](#string) |
| 76 - [Success](#success) | 76 - [Success](#success) |
| 77 - [Type](#type) | 77 - [Type](#type) |
| 78 - [TypeArguments](#typearguments) | 78 - [TypeArguments](#typearguments) |
| 79 - [Response](#response) | 79 - [Response](#response) |
| 80 - [Version](#version) | 80 - [Version](#version) |
| 81 - [VM](#vm) | 81 - [VM](#vm) |
| (...skipping 103 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 185 access to events pertaining to isolate births, deaths, and name changes. See [s
treamListen](#streamlisten) | 185 access to events pertaining to isolate births, deaths, and name changes. See [s
treamListen](#streamlisten) |
| 186 for a list of the well-known stream ids and their associated events. | 186 for a list of the well-known stream ids and their associated events. |
| 187 | 187 |
| 188 Events arrive asynchronously over the WebSocket and always have the | 188 Events arrive asynchronously over the WebSocket and always have the |
| 189 _streamId_ and _event_ properties: | 189 _streamId_ and _event_ properties: |
| 190 | 190 |
| 191 ``` | 191 ``` |
| 192 { | 192 { |
| 193 "event": { | 193 "event": { |
| 194 "type": "Event", | 194 "type": "Event", |
| 195 "eventType": "IsolateExit", | 195 "kind": "IsolateExit", |
| 196 "isolate": { | 196 "isolate": { |
| 197 "type": "@Isolate", | 197 "type": "@Isolate", |
| 198 "id": "isolates/33", | 198 "id": "isolates/33", |
| 199 "number": "51048743613", | 199 "number": "51048743613", |
| 200 "name": "worker-isolate" | 200 "name": "worker-isolate" |
| 201 } | 201 } |
| 202 } | 202 } |
| 203 "streamId": "Isolate" | 203 "streamId": "Isolate" |
| 204 } | 204 } |
| 205 ``` | 205 ``` |
| (...skipping 709 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 915 - The program has encountered an unhandled exception | 915 - The program has encountered an unhandled exception |
| 916 - The program has encountered a syntax error (or another Dart language error) | 916 - The program has encountered a syntax error (or another Dart language error) |
| 917 - The program has encountered an unhandled erroneous condition in native code | 917 - The program has encountered an unhandled erroneous condition in native code |
| 918 - The program has been terminated | 918 - The program has been terminated |
| 919 | 919 |
| 920 ### Event | 920 ### Event |
| 921 | 921 |
| 922 ``` | 922 ``` |
| 923 class Event extends Response { | 923 class Event extends Response { |
| 924 // What kind of event is this? | 924 // What kind of event is this? |
| 925 EventType eventType; | 925 EventKind kind; |
| 926 | 926 |
| 927 // The isolate with which this event is associated. | 927 // The isolate with which this event is associated. |
| 928 @Isolate isolate; | 928 @Isolate isolate; |
| 929 | 929 |
| 930 // The breakpoint associated with this event, if applicable. | 930 // The breakpoint associated with this event, if applicable. |
| 931 // | 931 // |
| 932 // This is provided for the events: | 932 // This is provided for the event kinds: |
| 933 // PauseBreakpoint | 933 // PauseBreakpoint |
| 934 // BreakpointAdded | 934 // BreakpointAdded |
| 935 // BreakpointRemoved | 935 // BreakpointRemoved |
| 936 // BreakpointResolved | 936 // BreakpointResolved |
| 937 Breakpoint breakpoint [optional]; | 937 Breakpoint breakpoint [optional]; |
| 938 | 938 |
| 939 // The top stack frame associated with this event, if applicable. | 939 // The top stack frame associated with this event, if applicable. |
| 940 // | 940 // |
| 941 // This is provided for the events: | 941 // This is provided for the event kinds: |
| 942 // PauseBreakpoint | 942 // PauseBreakpoint |
| 943 // PauseInterrupted | 943 // PauseInterrupted |
| 944 // PauseException | 944 // PauseException |
| 945 // | 945 // |
| 946 // For the Resume event, the top frame is provided at | 946 // For the Resume event, the top frame is provided at |
| 947 // all times except for the initial resume event that is delivered | 947 // all times except for the initial resume event that is delivered |
| 948 // when an isolate begins execution. | 948 // when an isolate begins execution. |
| 949 Frame topFrame [optional]; | 949 Frame topFrame [optional]; |
| 950 | 950 |
| 951 // The exception associated with this event, if this is a | 951 // The exception associated with this event, if this is a |
| 952 // PauseException event. | 952 // PauseException event. |
| 953 @Instance exception [optional]; | 953 @Instance exception [optional]; |
| 954 } | 954 } |
| 955 ``` | 955 ``` |
| 956 | 956 |
| 957 An _Event_ is an asynchronous notification from the VM. It is delivered | 957 An _Event_ is an asynchronous notification from the VM. It is delivered |
| 958 only when the client has subscribed to an event stream using the | 958 only when the client has subscribed to an event stream using the |
| 959 [streamListen](#streamListen) RPC. | 959 [streamListen](#streamListen) RPC. |
| 960 | 960 |
| 961 For more information, see [events](#events). | 961 For more information, see [events](#events). |
| 962 | 962 |
| 963 ### EventType | 963 ### EventKind |
| 964 | 964 |
| 965 ``` | 965 ``` |
| 966 enum EventType { | 966 enum EventKind { |
| 967 // Notification that a new isolate has started. | 967 // Notification that a new isolate has started. |
| 968 IsolateStart, | 968 IsolateStart, |
| 969 | 969 |
| 970 // Notification that an isolate has exited. | 970 // Notification that an isolate has exited. |
| 971 IsolateExit, | 971 IsolateExit, |
| 972 | 972 |
| 973 // Notification that isolate identifying information has changed. | 973 // Notification that isolate identifying information has changed. |
| 974 // Currently used to notify of changes to the isolate debugging name | 974 // Currently used to notify of changes to the isolate debugging name |
| 975 // via <code>setName</code>. | 975 // via <code>setName</code>. |
| 976 IsolateUpdate, | 976 IsolateUpdate, |
| (...skipping 23 matching lines...) Expand all Loading... |
| 1000 BreakpointResolved, | 1000 BreakpointResolved, |
| 1001 | 1001 |
| 1002 // A breakpoint has been removed. | 1002 // A breakpoint has been removed. |
| 1003 BreakpointRemoved, | 1003 BreakpointRemoved, |
| 1004 | 1004 |
| 1005 // A garbage collection event. | 1005 // A garbage collection event. |
| 1006 GC | 1006 GC |
| 1007 } | 1007 } |
| 1008 ``` | 1008 ``` |
| 1009 | 1009 |
| 1010 Adding new values to _EventKind_ is considered a backwards compatible |
| 1011 change. Clients should ignore unrecognized events. |
| 1012 |
| 1010 ### Field | 1013 ### Field |
| 1011 | 1014 |
| 1012 ``` | 1015 ``` |
| 1013 class @Field extends @Object { | 1016 class @Field extends @Object { |
| 1014 // The name of this field. | 1017 // The name of this field. |
| 1015 string name; | 1018 string name; |
| 1016 | 1019 |
| 1017 // The owner of this field, which can be either a Library or a | 1020 // The owner of this field, which can be either a Library or a |
| 1018 // Class. | 1021 // Class. |
| 1019 @Object owner; | 1022 @Object owner; |
| (...skipping 389 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 1409 } | 1412 } |
| 1410 ``` | 1413 ``` |
| 1411 | 1414 |
| 1412 An _Object_ is a persistent object that is owned by some isolate. | 1415 An _Object_ is a persistent object that is owned by some isolate. |
| 1413 | 1416 |
| 1414 ### Sentinel | 1417 ### Sentinel |
| 1415 | 1418 |
| 1416 ``` | 1419 ``` |
| 1417 class Sentinel extends Response { | 1420 class Sentinel extends Response { |
| 1418 // What kind of sentinel is this? | 1421 // What kind of sentinel is this? |
| 1419 SentinelType sentinelType; | 1422 SentinelKind kind; |
| 1420 | 1423 |
| 1421 // A reasonable string representation of this sentinel. | 1424 // A reasonable string representation of this sentinel. |
| 1422 string valueAsString; | 1425 string valueAsString; |
| 1423 } | 1426 } |
| 1424 ``` | 1427 ``` |
| 1425 | 1428 |
| 1426 A _Sentinel_ is used to indicate that the normal response is not available. | 1429 A _Sentinel_ is used to indicate that the normal response is not available. |
| 1427 | 1430 |
| 1428 We use a _Sentinel_ instead of an [error](#errors) for these cases because | 1431 We use a _Sentinel_ instead of an [error](#errors) for these cases because |
| 1429 they do not represent a problematic condition. They are normal. | 1432 they do not represent a problematic condition. They are normal. |
| 1430 | 1433 |
| 1431 ### SentinelType | 1434 ### SentinelKind |
| 1432 | 1435 |
| 1433 ``` | 1436 ``` |
| 1434 enum SentinelType { | 1437 enum SentinelKind { |
| 1435 // Indicates that the object referred to has been collected by the GC. | 1438 // Indicates that the object referred to has been collected by the GC. |
| 1436 Collected, | 1439 Collected, |
| 1437 | 1440 |
| 1438 // Indicates that an object id has expired. | 1441 // Indicates that an object id has expired. |
| 1439 Expired, | 1442 Expired, |
| 1440 | 1443 |
| 1441 // Indicates that a variable or field has not been initialized. | 1444 // Indicates that a variable or field has not been initialized. |
| 1442 NotInitialized, | 1445 NotInitialized, |
| 1443 | 1446 |
| 1444 // Indicates that a variable or field is in the process of being initialized. | 1447 // Indicates that a variable or field is in the process of being initialized. |
| 1445 BeingInitialized, | 1448 BeingInitialized, |
| 1446 | 1449 |
| 1447 // Indicates that a variable has been eliminated by the optimizing compiler. | 1450 // Indicates that a variable has been eliminated by the optimizing compiler. |
| 1448 OptimizedOut | 1451 OptimizedOut, |
| 1452 |
| 1453 // Reserved for future use. |
| 1454 Free, |
| 1449 } | 1455 } |
| 1450 ``` | 1456 ``` |
| 1451 | 1457 |
| 1452 A _SentinelType_ is used to distinguish different kinds of _Sentinel_ objects. | 1458 A _SentinelKind_ is used to distinguish different kinds of _Sentinel_ objects. |
| 1459 |
| 1460 Adding new values to _SentinelKind_ is considered a backwards |
| 1461 compatible change. Clients must handle this gracefully. |
| 1453 | 1462 |
| 1454 ### Script | 1463 ### Script |
| 1455 | 1464 |
| 1456 ``` | 1465 ``` |
| 1457 class @Script extends @Object { | 1466 class @Script extends @Object { |
| 1458 // The uri from which this script was loaded. | 1467 // The uri from which this script was loaded. |
| 1459 string uri; | 1468 string uri; |
| 1460 } | 1469 } |
| 1461 ``` | 1470 ``` |
| 1462 | 1471 |
| (...skipping 213 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 1676 // A list of isolates running in the VM. | 1685 // A list of isolates running in the VM. |
| 1677 @Isolate[] isolates | 1686 @Isolate[] isolates |
| 1678 } | 1687 } |
| 1679 ``` | 1688 ``` |
| 1680 | 1689 |
| 1681 ## Revision History | 1690 ## Revision History |
| 1682 | 1691 |
| 1683 version | comments | 1692 version | comments |
| 1684 ------- | -------- | 1693 ------- | -------- |
| 1685 0.0 | draft | 1694 0.0 | draft |
| OLD | NEW |