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

Side by Side Diff: runtime/vm/service/service.md

Issue 1153193006: Standardize on using "kind" to distinguish sub-varieties of a type. (Closed) Base URL: git@github.com:dart-lang/sdk.git@master
Patch Set: doc changes Created 5 years, 6 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 unified diff | Download patch
« no previous file with comments | « runtime/vm/service.cc ('k') | runtime/vm/service_event.cc » ('j') | no next file with comments »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
OLDNEW
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
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
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
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
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
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
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
OLDNEW
« no previous file with comments | « runtime/vm/service.cc ('k') | runtime/vm/service_event.cc » ('j') | no next file with comments »

Powered by Google App Engine
This is Rietveld 408576698