| OLD | NEW |
| 1 # Dart VM Service Protocol 3.0 | 1 # Dart VM Service Protocol 3.0 |
| 2 | 2 |
| 3 > Please post feedback to the [observatory-discuss group][discuss-list] | 3 > Please post feedback to the [observatory-discuss group][discuss-list] |
| 4 | 4 |
| 5 This document describes of _version 3.0_ of the Dart VM Service Protocol. This | 5 This document describes of _version 3.0_ of the Dart VM Service Protocol. This |
| 6 protocol is used to communicate with a running Dart Virtual Machine. | 6 protocol is used to communicate with a running Dart Virtual Machine. |
| 7 | 7 |
| 8 To use the Service Protocol, start the VM with the *--observe* flag. | 8 To use the Service Protocol, start the VM with the *--observe* flag. |
| 9 The VM will start a webserver which services protocol requests via WebSocket. | 9 The VM will start a webserver which services protocol requests via WebSocket. |
| 10 It is possible to make HTTP (non-WebSocket) requests, | 10 It is possible to make HTTP (non-WebSocket) requests, |
| (...skipping 449 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 460 string targetId, | 460 string targetId, |
| 461 string expression) | 461 string expression) |
| 462 ``` | 462 ``` |
| 463 | 463 |
| 464 The _evaluate_ RPC is used to evaluate an expression in the context of | 464 The _evaluate_ RPC is used to evaluate an expression in the context of |
| 465 some target. | 465 some target. |
| 466 | 466 |
| 467 _targetId_ may refer to a [Library](#library), [Class](#class), or | 467 _targetId_ may refer to a [Library](#library), [Class](#class), or |
| 468 [Instance](#instance). | 468 [Instance](#instance). |
| 469 | 469 |
| 470 If _targetId_ is a temporary id which has expired, then then _Expired_ | 470 If _targetId_ is a temporary id which has expired, then the _Expired_ |
| 471 [Sentinel](#sentinel) is returned. | 471 [Sentinel](#sentinel) is returned. |
| 472 | 472 |
| 473 If _targetId_ refers to an object which has been collected by the VM's | 473 If _targetId_ refers to an object which has been collected by the VM's |
| 474 garbage collector, then the _Collected_ [Sentinel](#sentinel) is | 474 garbage collector, then the _Collected_ [Sentinel](#sentinel) is |
| 475 returned. | 475 returned. |
| 476 | 476 |
| 477 If an error occurs while evaluating the expression, an [@Error](#error) | 477 If an error occurs while evaluating the expression, an [@Error](#error) |
| 478 reference will be returned. | 478 reference will be returned. |
| 479 | 479 |
| 480 If the expression is evaluated successfully, an [@Instance](#instance) | 480 If the expression is evaluated successfully, an [@Instance](#instance) |
| (...skipping 47 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 528 ``` | 528 ``` |
| 529 Object|Sentinel getObject(string isolateId, | 529 Object|Sentinel getObject(string isolateId, |
| 530 string objectId, | 530 string objectId, |
| 531 int offset [optional], | 531 int offset [optional], |
| 532 int count [optional]) | 532 int count [optional]) |
| 533 ``` | 533 ``` |
| 534 | 534 |
| 535 The _getObject_ RPC is used to lookup an _object_ from some isolate by | 535 The _getObject_ RPC is used to lookup an _object_ from some isolate by |
| 536 its _id_. | 536 its _id_. |
| 537 | 537 |
| 538 If _objectId_ is a temporary id which has expired, then then _Expired_ | 538 If _objectId_ is a temporary id which has expired, then the _Expired_ |
| 539 [Sentinel](#sentinel) is returned. | 539 [Sentinel](#sentinel) is returned. |
| 540 | 540 |
| 541 If _objectId_ refers to a heap object which has been collected by the VM's | 541 If _objectId_ refers to a heap object which has been collected by the VM's |
| 542 garbage collector, then the _Collected_ [Sentinel](#sentinel) is | 542 garbage collector, then the _Collected_ [Sentinel](#sentinel) is |
| 543 returned. | 543 returned. |
| 544 | 544 |
| 545 If _objectId_ refers to a non-heap object which has been deleted, then | 545 If _objectId_ refers to a non-heap object which has been deleted, then |
| 546 the _Collected_ [Sentinel](#sentinel) is returned. | 546 the _Collected_ [Sentinel](#sentinel) is returned. |
| 547 | 547 |
| 548 If the object handle has not expired and the object has not been | 548 If the object handle has not expired and the object has not been |
| (...skipping 765 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 1314 } | 1314 } |
| 1315 ``` | 1315 ``` |
| 1316 | 1316 |
| 1317 ### Function | 1317 ### Function |
| 1318 | 1318 |
| 1319 ``` | 1319 ``` |
| 1320 class @Function extends @Object { | 1320 class @Function extends @Object { |
| 1321 // The name of this function. | 1321 // The name of this function. |
| 1322 string name; | 1322 string name; |
| 1323 | 1323 |
| 1324 // The owner of this field, which can be a Library, Class, or a | 1324 // The owner of this function, which can be a Library, Class, or a Function. |
| 1325 // Function. | |
| 1326 @Library|@Class|@Function owner; | 1325 @Library|@Class|@Function owner; |
| 1327 | 1326 |
| 1328 // Is this function static? | 1327 // Is this function static? |
| 1329 bool static; | 1328 bool static; |
| 1330 | 1329 |
| 1331 // Is this function const? | 1330 // Is this function const? |
| 1332 bool const; | 1331 bool const; |
| 1333 } | 1332 } |
| 1334 ``` | 1333 ``` |
| 1335 | 1334 |
| 1336 An _@Function_ is a reference to a _Function_. | 1335 An _@Function_ is a reference to a _Function_. |
| 1337 | 1336 |
| 1338 | 1337 |
| 1339 ``` | 1338 ``` |
| 1340 class Function extends Object { | 1339 class Function extends Object { |
| 1341 // The name of this function. | 1340 // The name of this function. |
| 1342 string name; | 1341 string name; |
| 1343 | 1342 |
| 1344 // The owner of this field, which can be a Library, Class, or a | 1343 // The owner of this function, which can be a Library, Class, or a Function. |
| 1345 // Function. | |
| 1346 @Library|@Class|@Function owner; | 1344 @Library|@Class|@Function owner; |
| 1347 | 1345 |
| 1348 // The location of this function in the source code. | 1346 // The location of this function in the source code. |
| 1349 SourceLocation location [optional]; | 1347 SourceLocation location [optional]; |
| 1350 | 1348 |
| 1351 // The compiled code associated with this function. | 1349 // The compiled code associated with this function. |
| 1352 @Code code [optional]; | 1350 @Code code [optional]; |
| 1353 } | 1351 } |
| 1354 ``` | 1352 ``` |
| 1355 | 1353 |
| (...skipping 333 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 1689 | 1687 |
| 1690 // An instance of the built-in VM Map implementation. User-defined | 1688 // An instance of the built-in VM Map implementation. User-defined |
| 1691 // Maps will be PlainInstance. | 1689 // Maps will be PlainInstance. |
| 1692 Map, | 1690 Map, |
| 1693 | 1691 |
| 1694 // Vector instance kinds. | 1692 // Vector instance kinds. |
| 1695 Float32x4, | 1693 Float32x4, |
| 1696 Float64x2, | 1694 Float64x2, |
| 1697 Int32x4 | 1695 Int32x4 |
| 1698 | 1696 |
| 1699 // An instance of the built-in VM TypedData implementations. User-defined | 1697 // An instance of the built-in VM TypedData implementations. User-defined |
| 1700 // TypedDatas will be PlainInstance. | 1698 // TypedDatas will be PlainInstance. |
| 1701 Uint8ClampedList, | 1699 Uint8ClampedList, |
| 1702 Uint8List, | 1700 Uint8List, |
| 1703 Uint16List, | 1701 Uint16List, |
| 1704 Uint32List, | 1702 Uint32List, |
| 1705 Uint64List, | 1703 Uint64List, |
| 1706 Int8List, | 1704 Int8List, |
| 1707 Int16List, | 1705 Int16List, |
| 1708 Int32List, | 1706 Int32List, |
| 1709 Int64List, | 1707 Int64List, |
| (...skipping 12 matching lines...) Expand all Loading... |
| 1722 | 1720 |
| 1723 // An instance of the Dart class MirrorReference. | 1721 // An instance of the Dart class MirrorReference. |
| 1724 MirrorReference, | 1722 MirrorReference, |
| 1725 | 1723 |
| 1726 // An instance of the Dart class RegExp. | 1724 // An instance of the Dart class RegExp. |
| 1727 RegExp, | 1725 RegExp, |
| 1728 | 1726 |
| 1729 // An instance of the Dart class WeakProperty. | 1727 // An instance of the Dart class WeakProperty. |
| 1730 WeakProperty, | 1728 WeakProperty, |
| 1731 | 1729 |
| 1732 // An instance of the Dart class Type | 1730 // An instance of the Dart class Type. |
| 1733 Type, | 1731 Type, |
| 1734 | 1732 |
| 1735 // An instance of the Dart class TypeParamer | 1733 // An instance of the Dart class TypeParameter. |
| 1736 TypeParameter, | 1734 TypeParameter, |
| 1737 | 1735 |
| 1738 // An instance of the Dart class TypeRef | 1736 // An instance of the Dart class TypeRef. |
| 1739 TypeRef, | 1737 TypeRef, |
| 1740 | 1738 |
| 1741 // An instance of the Dart class BoundedType | 1739 // An instance of the Dart class BoundedType. |
| 1742 BoundedType, | 1740 BoundedType, |
| 1743 } | 1741 } |
| 1744 ``` | 1742 ``` |
| 1745 | 1743 |
| 1746 Adding new values to _InstanceKind_ is considered a backwards | 1744 Adding new values to _InstanceKind_ is considered a backwards |
| 1747 compatible change. Clients should treat unrecognized instance kinds | 1745 compatible change. Clients should treat unrecognized instance kinds |
| 1748 as _PlainInstance_. | 1746 as _PlainInstance_. |
| 1749 | 1747 |
| 1750 ### Isolate | 1748 ### Isolate |
| 1751 | 1749 |
| (...skipping 74 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 1826 _@Library_ is a reference to a _Library_. | 1824 _@Library_ is a reference to a _Library_. |
| 1827 | 1825 |
| 1828 ``` | 1826 ``` |
| 1829 class Library extends Object { | 1827 class Library extends Object { |
| 1830 // The name of this library. | 1828 // The name of this library. |
| 1831 string name; | 1829 string name; |
| 1832 | 1830 |
| 1833 // The uri of this library. | 1831 // The uri of this library. |
| 1834 string uri; | 1832 string uri; |
| 1835 | 1833 |
| 1836 // Is this library debuggable? Default true. | 1834 // Is this library debuggable? Default true. |
| 1837 bool debuggable; | 1835 bool debuggable; |
| 1838 | 1836 |
| 1839 // A list of the imports for this library. | 1837 // A list of the imports for this library. |
| 1840 LibraryDependency[] dependencies; | 1838 LibraryDependency[] dependencies; |
| 1841 | 1839 |
| 1842 // A list of the scripts which constitute this library. | 1840 // A list of the scripts which constitute this library. |
| 1843 @Script[] scripts; | 1841 @Script[] scripts; |
| 1844 | 1842 |
| 1845 // A list of the top-level variables in this library. | 1843 // A list of the top-level variables in this library. |
| 1846 @Field[] variables; | 1844 @Field[] variables; |
| (...skipping 332 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 2179 | 2177 |
| 2180 ``` | 2178 ``` |
| 2181 class UnresolvedSourceLocation extends Response { | 2179 class UnresolvedSourceLocation extends Response { |
| 2182 // The script containing the source location if the script has been loaded. | 2180 // The script containing the source location if the script has been loaded. |
| 2183 @Script script [optional]; | 2181 @Script script [optional]; |
| 2184 | 2182 |
| 2185 // The uri of the script containing the source location if the script | 2183 // The uri of the script containing the source location if the script |
| 2186 // has yet to be loaded. | 2184 // has yet to be loaded. |
| 2187 string scriptUri [optional]; | 2185 string scriptUri [optional]; |
| 2188 | 2186 |
| 2189 // An approximate token position for the source location. This may | 2187 // An approximate token position for the source location. This may |
| 2190 // change when the location is resolved. | 2188 // change when the location is resolved. |
| 2191 int tokenPos [optional]; | 2189 int tokenPos [optional]; |
| 2192 | 2190 |
| 2193 // An approximate line number for the source location. This may | 2191 // An approximate line number for the source location. This may |
| 2194 // change when the location is resolved. | 2192 // change when the location is resolved. |
| 2195 int line [optional]; | 2193 int line [optional]; |
| 2196 | 2194 |
| 2197 // An approximate column number for the source location. This may | 2195 // An approximate column number for the source location. This may |
| 2198 // change when the location is resolved. | 2196 // change when the location is resolved. |
| 2199 int column [optional]; | 2197 int column [optional]; |
| 2200 | 2198 |
| 2201 } | 2199 } |
| 2202 ``` | 2200 ``` |
| 2203 | 2201 |
| 2204 The _UnresolvedSourceLocation_ class is used to refer to an unresolved | 2202 The _UnresolvedSourceLocation_ class is used to refer to an unresolved |
| 2205 breakpoint location. As such, it is meant to approximate the final | 2203 breakpoint location. As such, it is meant to approximate the final |
| 2206 location of the breakpoint but it is not exact. | 2204 location of the breakpoint but it is not exact. |
| 2207 | 2205 |
| (...skipping 61 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 2269 ## Revision History | 2267 ## Revision History |
| 2270 | 2268 |
| 2271 version | comments | 2269 version | comments |
| 2272 ------- | -------- | 2270 ------- | -------- |
| 2273 1.0 | initial revision | 2271 1.0 | initial revision |
| 2274 2.0 | Describe protocol version 2.0. | 2272 2.0 | Describe protocol version 2.0. |
| 2275 3.0 | Describe protocol version 3.0. Added UnresolvedSourceLocation. Added Sen
tinel return to getIsolate. Add AddedBreakpointWithScriptUri. Removed Isolate.
entry. The type of VM.pid was changed from string to int. Added VMUpdate events
. Add offset and count parameters to getObject() and offset and count fields to
Instance. | 2273 3.0 | Describe protocol version 3.0. Added UnresolvedSourceLocation. Added Sen
tinel return to getIsolate. Add AddedBreakpointWithScriptUri. Removed Isolate.
entry. The type of VM.pid was changed from string to int. Added VMUpdate events
. Add offset and count parameters to getObject() and offset and count fields to
Instance. |
| 2276 | 2274 |
| 2277 | 2275 |
| 2278 [discuss-list]: https://groups.google.com/a/dartlang.org/forum/#!forum/observato
ry-discuss | 2276 [discuss-list]: https://groups.google.com/a/dartlang.org/forum/#!forum/observato
ry-discuss |
| OLD | NEW |