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 |