| 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 246 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 257 | 257 |
| 258 Many responses returned by the Service Protocol have an _id_ property. | 258 Many responses returned by the Service Protocol have an _id_ property. |
| 259 This is an identifier used to request an object from an isolate using | 259 This is an identifier used to request an object from an isolate using |
| 260 the [getObject](#getobject) RPC. If two responses have the same _id_ then they | 260 the [getObject](#getobject) RPC. If two responses have the same _id_ then they |
| 261 refer to the same object. The converse is not true: the same object | 261 refer to the same object. The converse is not true: the same object |
| 262 may sometimes be returned with two different values for _id_. | 262 may sometimes be returned with two different values for _id_. |
| 263 | 263 |
| 264 The _id_ property should be treated as an opaque string by the client: | 264 The _id_ property should be treated as an opaque string by the client: |
| 265 it is not meant to be parsed. | 265 it is not meant to be parsed. |
| 266 | 266 |
| 267 An id can be either _temporary_ or _permanent_: | 267 An id can be either _temporary_ or _fixed_: |
| 268 | 268 |
| 269 * A _temporary_ id can expire over time. The VM allocates certain ids | 269 * A _temporary_ id can expire over time. The VM allocates certain ids |
| 270 in a ring which evicts old ids over time. | 270 in a ring which evicts old ids over time. |
| 271 | 271 |
| 272 * A _permanent_ id will never expire, but the object it refers to may | 272 * A _fixed_ id will never expire, but the object it refers to may |
| 273 be collected. The VM uses permanent ids for objects like scripts, | 273 be collected. The VM uses fixed ids for objects like scripts, |
| 274 libraries, and classes. | 274 libraries, and classes. |
| 275 | 275 |
| 276 TODO: Describe how to distinguish temporary/permanent | 276 If an id is fixed, the _fixedId_ property will be true. If an id is temporary |
| 277 the _fixedId_ property will be omitted. |
| 277 | 278 |
| 278 Sometimes a temporary id may expire. In this case, some RPCs may return | 279 Sometimes a temporary id may expire. In this case, some RPCs may return |
| 279 an _Expired_ [Sentinel](#sentinel) to indicate this. | 280 an _Expired_ [Sentinel](#sentinel) to indicate this. |
| 280 | 281 |
| 281 The object referred to by an id may be collected by the VM's garbage | 282 The object referred to by an id may be collected by the VM's garbage |
| 282 collector. In this case, some RPCs may return a _Collected_ [Sentinel](#sentine
l) | 283 collector. In this case, some RPCs may return a _Collected_ [Sentinel](#sentine
l) |
| 283 to indicate this. | 284 to indicate this. |
| 284 | 285 |
| 285 Many objects also have a _name_ property. This is provided so that | 286 Many objects also have a _name_ property. This is provided so that |
| 286 objects can be displayed in a way that a Dart language programmer | 287 objects can be displayed in a way that a Dart language programmer |
| (...skipping 436 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 723 @Instance|Sentinel value; | 724 @Instance|Sentinel value; |
| 724 } | 725 } |
| 725 ``` | 726 ``` |
| 726 | 727 |
| 727 A _BoundField_ represents a field bound to a particular value in an | 728 A _BoundField_ represents a field bound to a particular value in an |
| 728 _Instance_. | 729 _Instance_. |
| 729 | 730 |
| 730 If the field is uninitialized, the _value_ will be the | 731 If the field is uninitialized, the _value_ will be the |
| 731 _NotInitialized_ [Sentinel](#sentinel). | 732 _NotInitialized_ [Sentinel](#sentinel). |
| 732 | 733 |
| 733 If the field is being initialized, the _value_ will be the | 734 If the field is being initialized, the _value_ will be the |
| 734 _BeingInitialized_ [Sentinel](#sentinel). | 735 _BeingInitialized_ [Sentinel](#sentinel). |
| 735 | 736 |
| 736 ### BoundVariable | 737 ### BoundVariable |
| 737 | 738 |
| 738 ``` | 739 ``` |
| 739 class BoundVariable { | 740 class BoundVariable { |
| 740 string name; | 741 string name; |
| 741 @Instance|Sentinel value; | 742 @Instance|Sentinel value; |
| 742 } | 743 } |
| 743 ``` | 744 ``` |
| (...skipping 92 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 836 @Class[] classes; | 837 @Class[] classes; |
| 837 } | 838 } |
| 838 ``` | 839 ``` |
| 839 | 840 |
| 840 ### Code | 841 ### Code |
| 841 | 842 |
| 842 ``` | 843 ``` |
| 843 class @Code extends @Object { | 844 class @Code extends @Object { |
| 844 // A name for this code object. | 845 // A name for this code object. |
| 845 string name; | 846 string name; |
| 846 | 847 |
| 847 // What kind of code object is this? | 848 // What kind of code object is this? |
| 848 CodeKind kind; | 849 CodeKind kind; |
| 849 } | 850 } |
| 850 ``` | 851 ``` |
| 851 | 852 |
| 852 _@Code_ is a reference to a _Code_ object. | 853 _@Code_ is a reference to a _Code_ object. |
| 853 | 854 |
| 854 ``` | 855 ``` |
| 855 class @Code extends @Object { | 856 class @Code extends @Object { |
| 856 // A name for this code object. | 857 // A name for this code object. |
| 857 string name; | 858 string name; |
| 858 | 859 |
| 859 // What kind of code object is this? | 860 // What kind of code object is this? |
| 860 CodeKind kind; | 861 CodeKind kind; |
| 861 } | 862 } |
| 862 ``` | 863 ``` |
| 863 | 864 |
| 864 A _Code_ object represents compiled code in the Dart VM. | 865 A _Code_ object represents compiled code in the Dart VM. |
| 865 | 866 |
| 866 ### CodeCoverage | 867 ### CodeCoverage |
| 867 | 868 |
| 868 TODO | 869 TODO |
| (...skipping 631 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 1500 | 1501 |
| 1501 We use a _Sentinel_ instead of an [error](#errors) for these cases because | 1502 We use a _Sentinel_ instead of an [error](#errors) for these cases because |
| 1502 they do not represent a problematic condition. They are normal. | 1503 they do not represent a problematic condition. They are normal. |
| 1503 | 1504 |
| 1504 ### SentinelType | 1505 ### SentinelType |
| 1505 | 1506 |
| 1506 ``` | 1507 ``` |
| 1507 enum SentinelType { | 1508 enum SentinelType { |
| 1508 // Indicates that the object referred to has been collected by the GC. | 1509 // Indicates that the object referred to has been collected by the GC. |
| 1509 Collected, | 1510 Collected, |
| 1510 | 1511 |
| 1511 // Indicates that an object id has expired. | 1512 // Indicates that an object id has expired. |
| 1512 Expired, | 1513 Expired, |
| 1513 | 1514 |
| 1514 // Indicates that a variable or field has not been initialized. | 1515 // Indicates that a variable or field has not been initialized. |
| 1515 NotInitialized, | 1516 NotInitialized, |
| 1516 | 1517 |
| 1517 // Indicates that a variable or field is in the process of being initialized. | 1518 // Indicates that a variable or field is in the process of being initialized. |
| 1518 BeingInitialized, | 1519 BeingInitialized, |
| 1519 | 1520 |
| 1520 // Indicates that a variable has been eliminated by the optimizing compiler. | 1521 // Indicates that a variable has been eliminated by the optimizing compiler. |
| 1521 OptimizedOut | 1522 OptimizedOut |
| 1522 } | 1523 } |
| 1523 ``` | 1524 ``` |
| 1524 | 1525 |
| 1525 A _SentinelType_ is used to distinguish different kinds of _Sentinel_ objects. | 1526 A _SentinelType_ is used to distinguish different kinds of _Sentinel_ objects. |
| 1526 | 1527 |
| 1527 ### Script | 1528 ### Script |
| 1528 | 1529 |
| 1529 ``` | 1530 ``` |
| (...skipping 166 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 1696 string name; | 1697 string name; |
| 1697 } | 1698 } |
| 1698 ``` | 1699 ``` |
| 1699 | 1700 |
| 1700 _@TypeArguments_ is a reference to a _TypeArguments_ object. | 1701 _@TypeArguments_ is a reference to a _TypeArguments_ object. |
| 1701 | 1702 |
| 1702 ``` | 1703 ``` |
| 1703 class TypeArguments extends Object { | 1704 class TypeArguments extends Object { |
| 1704 // A name for this type argument list. | 1705 // A name for this type argument list. |
| 1705 string name; | 1706 string name; |
| 1706 | 1707 |
| 1707 // A list of types. | 1708 // A list of types. |
| 1708 @Type[] types; | 1709 @Type[] types; |
| 1709 } | 1710 } |
| 1710 ``` | 1711 ``` |
| 1711 | 1712 |
| 1712 A _TypeArguments_ object represents the type argument vector for some | 1713 A _TypeArguments_ object represents the type argument vector for some |
| 1713 instantiated generic type. | 1714 instantiated generic type. |
| 1714 | 1715 |
| 1715 ### Response | 1716 ### Response |
| 1716 | 1717 |
| (...skipping 53 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 1770 // A list of isolates running in the VM. | 1771 // A list of isolates running in the VM. |
| 1771 @Isolate[] isolates | 1772 @Isolate[] isolates |
| 1772 } | 1773 } |
| 1773 ``` | 1774 ``` |
| 1774 | 1775 |
| 1775 ## Revision History | 1776 ## Revision History |
| 1776 | 1777 |
| 1777 version | comments | 1778 version | comments |
| 1778 ------- | -------- | 1779 ------- | -------- |
| 1779 0.0 | draft | 1780 0.0 | draft |
| OLD | NEW |