Permalink
Switch branches/tags
analyzer-0.32.1 analyzer-0.32.0 analyzer-0.31.2-alpha.2 analyzer-0.31.2-alpha.1 analyzer-0.31.2-alpha.0 analyzer-0.31.1 analyzer-0.31.0+1 analyzer-0.31.0 2.0.0-dev.68.0 2.0.0-dev.67.0 2.0.0-dev.66.0 2.0.0-dev.65.0 2.0.0-dev.64.2 2.0.0-dev.64.1 2.0.0-dev.64.0 2.0.0-dev.63.0 2.0.0-dev.62.0 2.0.0-dev.61.0 2.0.0-dev.60.0 2.0.0-dev.59.0 2.0.0-dev.58.0 2.0.0-dev.57.0 2.0.0-dev.56.0 2.0.0-dev.55.0 2.0.0-dev.54.0 2.0.0-dev.53.0 2.0.0-dev.52.0 2.0.0-dev.51.0 2.0.0-dev.50.0 2.0.0-dev.49.0 2.0.0-dev.48.0 2.0.0-dev.47.0 2.0.0-dev.46.0 2.0.0-dev.45.0 2.0.0-dev.44.0 2.0.0-dev.43.0 2.0.0-dev.42.0 2.0.0-dev.41.0 2.0.0-dev.40.0 2.0.0-dev.39.0 2.0.0-dev.38.0 2.0.0-dev.37.0 2.0.0-dev.36.0 2.0.0-dev.35 2.0.0-dev.34.0 2.0.0-dev.33.0 2.0.0-dev.32.0 2.0.0-dev.31.0 2.0.0-dev.30.0 2.0.0-dev.29.0 2.0.0-dev.28.0 2.0.0-dev.27.0 2.0.0-dev.26.0 2.0.0-dev.25.0 2.0.0-dev.24.0 2.0.0-dev.23.0 2.0.0-dev.22.0 2.0.0-dev.21.0 2.0.0-dev.20.0 2.0.0-dev.19.0 2.0.0-dev.18.0 2.0.0-dev.17.0 2.0.0-dev.16.0 2.0.0-dev.15.0 2.0.0-dev.14.0 2.0.0-dev.13.0 2.0.0-dev.12.0 2.0.0-dev.11.0 2.0.0-dev.10.0 2.0.0-dev.9.0 2.0.0-dev.8.0 2.0.0-dev.7.0 2.0.0-dev.6.0 2.0.0-dev.5.0 2.0.0-dev.4.0 2.0.0-dev.3.0 2.0.0-dev.2.0 2.0.0-dev.1.0 2.0.0-dev.0.1 2.0.0-dev.0.0 1.25.0-dev.16.4 1.25.0-dev.16.3 1.25.0-dev.16.2 1.25.0-dev.16.1 1.25.0-dev.16.0 1.25.0-dev.15.0 1.25.0-dev.14.0 1.25.0-dev.13.0 1.25.0-dev.12.0 1.25.0-dev.11.0 1.25.0-dev.10.0 1.25.0-dev.9.0 1.25.0-dev.8.0 1.25.0-dev.7.0 1.25.0-dev.6.0 1.25.0-dev.5.0 1.25.0-dev.4.0 1.25.0-dev.3.0 1.25.0-dev.2.1 1.25.0-dev.2.0
Nothing to show
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
2675 lines (2040 sloc) 67.9 KB

Dart VM Service Protocol 3.9

Please post feedback to the observatory-discuss group

This document describes of version 3.9 of the Dart VM Service Protocol. This protocol is used to communicate with a running Dart Virtual Machine.

To use the Service Protocol, start the VM with the --observe flag. The VM will start a webserver which services protocol requests via WebSocket. It is possible to make HTTP (non-WebSocket) requests, but this does not allow access to VM events and is not documented here.

The Service Protocol uses JSON-RPC 2.0.

Table of Contents

RPCs, Requests, and Responses

An RPC request is a JSON object sent to the server. Here is an example getVersion request:

{
  "jsonrpc": "2.0",
  "method": "getVersion",
  "params": {},
  "id": "1"
}

The id property must be a string, number, or null. The Service Protocol optionally accepts requests without the jsonprc property.

An RPC response is a JSON object (http://json.org/). The response always specifies an id property to pair it with the corresponding request. If the RPC was successful, the result property provides the result.

Here is an example response for our getVersion request above:

{
  "jsonrpc": "2.0",
  "result": {
    "type": "Version",
    "major": 3,
    "minor": 5
  }
  "id": "1"
}

Parameters for RPC requests are always provided as named parameters. The JSON-RPC spec provides for positional parameters as well, but they are not supported by the Dart VM.

By convention, every response returned by the Service Protocol is a subtype of Response and provides a type parameter which can be used to distinguish the exact return type. In the example above, the Version type is returned.

Here is an example streamListen request which provides a parameter:

{
  "jsonrpc": "2.0",
  "method": "streamListen",
  "params": {
    "streamId": "GC",
  },
  "id": "2"
}

When an RPC encounters an error, it is provided in the error property of the response object. JSON-RPC errors always provide code, message, and data properties.

Here is an example error response for our streamListen request above. This error would be generated if we were attempting to subscribe to the GC stream multiple times from the same client.

{
  "jsonrpc": "2.0",
  "error": {
    "code": 103,
    "message": "Stream already subscribed",
    "data": {
      "details": "The stream 'GC' is already subscribed"
    }
  }
  "id": "2"
}

In addition to the error codes specified in the JSON-RPC spec, we use the following application specific error codes:

code message meaning
100 Feature is disabled The operation is unable to complete because a feature is disabled
101 VM must be paused This operation is only valid when the VM is paused
102 Cannot add breakpoint The VM is unable to add a breakpoint at the specified line or function
103 Stream already subscribed The client is already subscribed to the specified streamId
104 Stream not subscribed The client is not subscribed to the specified streamId
105 Isolate must be runnable This operation cannot happen until the isolate is runnable
106 Isolate must be paused This operation is only valid when the isolate is paused
107 Cannot resume execution The isolate could not be resumed
108 Isolate is reloading The isolate is currently processing another reload request
109 Isolate cannot be reloaded The isolate has an unhandled exception and can no longer be reloaded
110 Isolate must have reloaded Failed to find differences in last hot reload request
111 Service already registered Service with such name has already been registered by this client
112 Service disappeared Failed to fulfill service request, likely service handler is no longer available
113 Expression compilation error Request to compile expression failed

Events

By using the streamListen and streamCancel RPCs, a client may request to be notified when an event is posted to a specific stream in the VM. Every stream has an associated stream id which is used to name that stream.

Each stream provides access to certain kinds of events. For example the Isolate stream provides access to events pertaining to isolate births, deaths, and name changes. See streamListen for a list of the well-known stream ids and their associated events.

Stream events arrive asynchronously over the WebSocket. They're structured as JSON-RPC 2.0 requests with no id property. The method property will be streamNotify, and the params will have streamId and event properties:

{
  "json-rpc": "2.0",
  "method": "streamNotify",
  "params": {
    "streamId": "Isolate",
    "event": {
      "type": "Event",
      "kind": "IsolateExit",
      "isolate": {
        "type": "@Isolate",
        "id": "isolates/33",
        "number": "51048743613",
        "name": "worker-isolate"
      }
    }
  }
}

It is considered a backwards compatible change to add a new type of event to an existing stream. Clients should be written to handle this gracefully.

Types

By convention, every result and event provided by the Service Protocol is a subtype of Response and has the type property. This allows the client to distinguish different kinds of responses. For example, information about a Dart function is returned using the Function type.

If the type of a response begins with the @ character, then that response is a reference. If the type name of a response does not begin with the @ character, it is an object. A reference is intended to be a subset of an object which provides enough information to generate a reasonable looking reference to the object.

For example, an @Isolate reference has the type, id, name and number properties:

  "result": {
    "type": "@Isolate",
    "id": "isolates/33",
    "number": "51048743613"
    "name": "worker-isolate"
  }

But an Isolate object has more information:

  "result": {
    "type": "Isolate",
    "id": "isolates/33",
    "number": "51048743613"
    "name": "worker-isolate"
    "rootLib": { ... }
    "entry": ...
    "heaps": ...
     ...
  }

IDs and Names

Many responses returned by the Service Protocol have an id property. This is an identifier used to request an object from an isolate using the getObject RPC. If two responses have the same id then they refer to the same object. The converse is not true: the same object may sometimes be returned with two different values for id.

The id property should be treated as an opaque string by the client: it is not meant to be parsed.

An id can be either temporary or fixed:

  • A temporary id can expire over time. The VM allocates certain ids in a ring which evicts old ids over time.

  • A fixed id will never expire, but the object it refers to may be collected. The VM uses fixed ids for objects like scripts, libraries, and classes.

If an id is fixed, the fixedId property will be true. If an id is temporary the fixedId property will be omitted.

Sometimes a temporary id may expire. In this case, some RPCs may return an Expired Sentinel to indicate this.

The object referred to by an id may be collected by the VM's garbage collector. In this case, some RPCs may return a Collected Sentinel to indicate this.

Many objects also have a name property. This is provided so that objects can be displayed in a way that a Dart language programmer would find familiar. Names are not unique.

Versioning

The getVersion RPC can be used to find the version of the protocol returned by a VM. The Version response has a major and a minor version number:

  "result": {
    "type": "Version",
    "major": 3,
    "minor": 5
  }

The major version number is incremented when the protocol is changed in a potentially incompatible way. An example of an incompatible change is removing a non-optional property from a result.

The minor version number is incremented when the protocol is changed in a backwards compatible way. An example of a backwards compatible change is adding a property to a result.

Certain changes that would normally not be backwards compatible are considered backwards compatible for the purposes of versioning. Specifically, additions can be made to the EventKind and InstanceKind enumerated types and the client must handle this gracefully. See the notes on these enumerated types for more information.

Private RPCs, Types, and Properties

Any RPC, type, or property which begins with an underscore is said to be private. These RPCs, types, and fields can be changed at any time without changing major or minor version numbers.

The intention is that the Service Protocol will evolve by adding private RPCs which may, over time, migrate to the public api as they become stable. Some private types and properties expose VM specific implementation state and will never be appropriate to add to the public api.

Public RPCs

The following is a list of all public RPCs supported by the Service Protocol.

An RPC is described using the following format:

ReturnType methodName(parameterType1 parameterName1,
                      parameterType2 parameterName2,
                      ...)

If an RPC says it returns type T it may actually return T or any subtype of T. For example, an RPC which is declared to return @Object may actually return @Instance.

If an RPC can return one or more independent types, this is indicated with the vertical bar:

ReturnType1|ReturnType2

Any RPC may return an error response as described above.

Some parameters are optional. This is indicated by the text [optional] following the parameter name:

ReturnType methodName(parameterType parameterName [optional])

A description of the return types and parameter types is provided in the section on public types.

addBreakpoint

Breakpoint addBreakpoint(string isolateId,
                         string scriptId,
                         int line,
                         int column [optional])

The addBreakpoint RPC is used to add a breakpoint at a specific line of some script.

The scriptId parameter is used to specify the target script.

The line parameter is used to specify the target line for the breakpoint. If there are multiple possible breakpoints on the target line, then the VM will place the breakpoint at the location which would execute soonest. If it is not possible to set a breakpoint at the target line, the breakpoint will be added at the next possible breakpoint location within the same function.

The column parameter may be optionally specified. This is useful for targeting a specific breakpoint on a line with multiple possible breakpoints.

If no breakpoint is possible at that line, the 102 (Cannot add breakpoint) error code is returned.

Note that breakpoints are added and removed on a per-isolate basis.

See Breakpoint.

addBreakpointWithScriptUri

Breakpoint addBreakpointWithScriptUri(string isolateId,
                                      string scriptUri,
                                      int line,
                                      int column [optional])

The addBreakpoint RPC is used to add a breakpoint at a specific line of some script. This RPC is useful when a script has not yet been assigned an id, for example, if a script is in a deferred library which has not yet been loaded.

The scriptUri parameter is used to specify the target script.

The line parameter is used to specify the target line for the breakpoint. If there are multiple possible breakpoints on the target line, then the VM will place the breakpoint at the location which would execute soonest. If it is not possible to set a breakpoint at the target line, the breakpoint will be added at the next possible breakpoint location within the same function.

The column parameter may be optionally specified. This is useful for targeting a specific breakpoint on a line with multiple possible breakpoints.

If no breakpoint is possible at that line, the 102 (Cannot add breakpoint) error code is returned.

Note that breakpoints are added and removed on a per-isolate basis.

See Breakpoint.

addBreakpointAtEntry

Breakpoint addBreakpointAtEntry(string isolateId,
                                string functionId)

The addBreakpointAtEntry RPC is used to add a breakpoint at the entrypoint of some function.

If no breakpoint is possible at the function entry, the 102 (Cannot add breakpoint) error code is returned.

See Breakpoint.

Note that breakpoints are added and removed on a per-isolate basis.

evaluate

@Instance|@Error|Sentinel evaluate(string isolateId,
                                   string targetId,
                                   string expression,
                                   map<string,string> scope [optional])

The evaluate RPC is used to evaluate an expression in the context of some target.

targetId may refer to a Library, Class, or Instance.

If targetId is a temporary id which has expired, then the Expired Sentinel is returned.

If targetId refers to an object which has been collected by the VM's garbage collector, then the Collected Sentinel is returned.

If scope is provided, it should be a map from identifiers to object ids. These bindings will be added to the scope in which the expression is evaluated, which is a child scope of the class or library for instance/class or library targets respectively. This means bindings provided in scope may shadow instance members, class members and top-level members.

If expression is failed to parse and compile, then rpc error 113 "Expression compilation error" is returned.

If an error occurs while evaluating the expression, an @Error reference will be returned.

If the expression is evaluated successfully, an @Instance reference will be returned.

evaluateInFrame

@Instance|@Error|Sentinel evaluateInFrame(string isolateId,
                                          int frameIndex,
                                          string expression,
                                          map<string,string> scope [optional])

The evaluateInFrame RPC is used to evaluate an expression in the context of a particular stack frame. frameIndex is the index of the desired Frame, with an index of 0 indicating the top (most recent) frame.

If scope is provided, it should be a map from identifiers to object ids. These bindings will be added to the scope in which the expression is evaluated, which is a child scope of the frame's current scope. This means bindings provided in scope may shadow instance members, class members, top-level members, parameters and locals.

If expression is failed to parse and compile, then rpc error 113 "Expression compilation error" is returned.

If an error occurs while evaluating the expression, an @Error reference will be returned.

If the expression is evaluated successfully, an @Instance reference will be returned.

getFlagList

FlagList getFlagList()

The getFlagList RPC returns a list of all command line flags in the VM along with their current values.

See FlagList.

getIsolate

Isolate|Sentinel getIsolate(string isolateId)

The getIsolate RPC is used to lookup an Isolate object by its id.

If isolateId refers to an isolate which has exited, then the Collected Sentinel is returned.

See Isolate.

getObject

Object|Sentinel getObject(string isolateId,
                          string objectId,
                          int offset [optional],
                          int count [optional])

The getObject RPC is used to lookup an object from some isolate by its id.

If objectId is a temporary id which has expired, then the Expired Sentinel is returned.

If objectId refers to a heap object which has been collected by the VM's garbage collector, then the Collected Sentinel is returned.

If objectId refers to a non-heap object which has been deleted, then the Collected Sentinel is returned.

If the object handle has not expired and the object has not been collected, then an Object will be returned.

The offset and count parameters are used to request subranges of Instance objects with the kinds: String, List, Map, Uint8ClampedList, Uint8List, Uint16List, Uint32List, Uint64List, Int8List, Int16List, Int32List, Int64List, Flooat32List, Float64List, Inst32x3List, Float32x4List, and Float64x2List. These parameters are otherwise ignored.

getStack

Stack getStack(string isolateId)

The getStack RPC is used to retrieve the current execution stack and message queue for an isolate. The isolate does not need to be paused.

See Stack.

getSourceReport

SourceReport getSourceReport(string isolateId,
                             SourceReportKind[] reports,
                             string scriptId [optional],
                             int tokenPos [optional],
                             int endTokenPos [optional],
                             bool forceCompile [optional])

The getSourceReport RPC is used to generate a set of reports tied to source locations in an isolate.

The reports parameter is used to specify which reports should be generated. The reports parameter is a list, which allows multiple reports to be generated simultaneously from a consistent isolate state. The reports parameter is allowed to be empty (this might be used to force compilation of a particular subrange of some script).

The available report kinds are:

report kind meaning
Coverage Provide code coverage information
PossibleBreakpoints Provide a list of token positions which correspond to possible breakpoints.

The scriptId parameter is used to restrict the report to a particular script. When analyzing a particular script, either or both of the tokenPos and endTokenPos parameters may be provided to restrict the analysis to a subrange of a script (for example, these can be used to restrict the report to the range of a particular class or function).

If the scriptId parameter is not provided then the reports are generated for all loaded scripts and the tokenPos and endTokenPos parameters are disallowed.

The forceCompilation parameter can be used to force compilation of all functions in the range of the report. Forcing compilation can cause a compilation error, which could terminate the running Dart program. If this parameter is not provided, it is considered to have the value false.

See SourceReport.

getVersion

Version getVersion()

The getVersion RPC is used to determine what version of the Service Protocol is served by a VM.

See Version.

getVM

VM getVM()

The getVM RPC returns global information about a Dart virtual machine.

See VM.

pause

Success pause(string isolateId)

The pause RPC is used to interrupt a running isolate. The RPC enqueues the interrupt request and potentially returns before the isolate is paused.

When the isolate is paused an event will be sent on the Debug stream.

See Success.

kill

Success kill(string isolateId)

The kill RPC is used to kill an isolate as if by dart:isolate's Isolate.kill(IMMEDIATE).

The isolate is killed regardless of whether it is paused or running.

See Success.

reloadSources

ReloadReport reloadSources(string isolateId,
                           bool force [optional],
                           bool pause [optional],
                           string rootLibUri [optional],
                           string packagesUri [optional])

The reloadSources RPC is used to perform a hot reload of an Isolate's sources.

if the force parameter is provided, it indicates that all of the Isolate's sources should be reloaded regardless of modification time.

if the pause parameter is provided, the isolate will pause immediately after the reload.

if the rootLibUri parameter is provided, it indicates the new uri to the Isolate's root library.

if the packagesUri parameter is provided, it indicates the new uri to the Isolate's package map (.packages) file.

removeBreakpoint

Success removeBreakpoint(string isolateId,
                         string breakpointId)

The removeBreakpoint RPC is used to remove a breakpoint by its id.

Note that breakpoints are added and removed on a per-isolate basis.

See Success.

resume

Success resume(string isolateId,
               StepOption step [optional],
               int frameIndex [optional])

The resume RPC is used to resume execution of a paused isolate.

If the step parameter is not provided, the program will resume regular execution.

If the step parameter is provided, it indicates what form of single-stepping to use.

step meaning
Into Single step, entering function calls
Over Single step, skipping over function calls
Out Single step until the current function exits
Rewind Immediately exit the top frame(s) without executing any code. Isolate will be paused at the call of the last exited function.

The frameIndex parameter is only used when the step parameter is Rewind. It specifies the stack frame to rewind to. Stack frame 0 is the currently executing function, so frameIndex must be at least 1.

If the frameIndex parameter is not provided, it defaults to 1.

See Success, StepOption.

setExceptionPauseMode

Success setExceptionPauseMode(string isolateId,
                              ExceptionPauseMode mode)

The setExceptionPauseMode RPC is used to control if an isolate pauses when an exception is thrown.

mode meaning
None Do not pause isolate on thrown exceptions
Unhandled Pause isolate on unhandled exceptions
All Pause isolate on all thrown exceptions

setFlag

Success setFlag(string name,
                string value)

The setFlag RPC is used to set a VM flag at runtime. Returns an error if the named flag does not exist, the flag may not be set at runtime, or the value is of the wrong type for the flag.

The following flags may be set at runtime:

  • pause_isolates_on_start
  • pause_isolates_on_exit
  • pause_isolates_on_unhandled_exceptions

See Success.

setLibraryDebuggable

Success setLibraryDebuggable(string isolateId,
                             string libraryId,
                             bool isDebuggable)

The setLibraryDebuggable RPC is used to enable or disable whether breakpoints and stepping work for a given library.

See Success.

setName

Success setName(string isolateId,
                string name)

The setName RPC is used to change the debugging name for an isolate.

See Success.

setVMName

Success setVMName(string name)

The setVMName RPC is used to change the debugging name for the vm.

See Success.

streamCancel

Success streamCancel(string streamId)

The streamCancel RPC cancels a stream subscription in the VM.

If the client is not subscribed to the stream, the 104 (Stream not subscribed) error code is returned.

See Success.

streamListen

Success streamListen(string streamId)

The streamListen RPC subscribes to a stream in the VM. Once subscribed, the client will begin receiving events from the stream.

If the client is not subscribed to the stream, the 103 (Stream already subscribed) error code is returned.

The streamId parameter may have the following published values:

streamId event types provided
VM VMUpdate
Isolate IsolateStart, IsolateRunnable, IsolateExit, IsolateUpdate, IsolateReload, ServiceExtensionAdded
Debug PauseStart, PauseExit, PauseBreakpoint, PauseInterrupted, PauseException, PausePostRequest, Resume, BreakpointAdded, BreakpointResolved, BreakpointRemoved, Inspect, None
GC GC
Extension Extension
Timeline TimelineEvents

Additionally, some embedders provide the Stdout and Stderr streams. These streams allow the client to subscribe to writes to stdout and stderr.

streamId event types provided
Stdout WriteEvent
Stderr WriteEvent

It is considered a backwards compatible change to add a new type of event to an existing stream. Clients should be written to handle this gracefully, perhaps by warning and ignoring.

See Success.

Public Types

The following is a list of all public types produced by the Service Protocol.

We define a small set of primitive types, based on JSON equivalents.

type meaning
string JSON string values
bool JSON true, false
int JSON numbers without fractions or exponents
float any JSON number

Note that the Service Protocol does not use JSON null.

We describe the format of our JSON objects with the following class format:

class T {
  string name;
  int count;
  ...
}

This describes a JSON object type T with some set of expected properties.

Types are organized into an inheritance hierarchy. If type T extends type S...

class S {
  string a;
}

class T extends S {
  string b;
}

...then that means that all properties of S are also present in type T. In the example above, type T would have the expected properties a and b.

If a property has an Array type, it is written with brackets:

  PropertyType[] arrayProperty;

If a property is optional, it is suffixed with the text [optional]:

  PropertyType optionalProperty [optional];

If a property can have multiple independent types, we denote this with a vertical bar:

  PropertyType1|PropertyType2 complexProperty;

We also allow parenthesis on type expressions. This is useful when a property is an Array of multiple independent types:

  (PropertyType1|PropertyType2)[]

When a string is only permitted to take one of a certain set of values, we indicate this by the use of the enum format:

enum PermittedValues {
  Value1,
  Value2
}

This means that PermittedValues is a string with two potential values, Value1 and Value2.

BoundField

class BoundField {
  @Field decl;
  @Instance|Sentinel value;
}

A BoundField represents a field bound to a particular value in an Instance.

If the field is uninitialized, the value will be the NotInitialized Sentinel.

If the field is being initialized, the value will be the BeingInitialized Sentinel.

BoundVariable

class BoundVariable {
  string name;
  @Instance|Sentinel value;

  // The token position where this variable was declared.
  int declarationTokenPos;

  // The first token position where this variable is visible to the scope.
  int scopeStartTokenPos;

  // The last token position where this variable is visible to the scope.
  int scopeEndTokenPos;
}

A BoundVariable represents a local variable bound to a particular value in a Frame.

If the variable is uninitialized, the value will be the NotInitialized Sentinel.

If the variable is being initialized, the value will be the BeingInitialized Sentinel.

If the variable has been optimized out by the compiler, the value will be the OptimizedOut Sentinel.

Breakpoint

class Breakpoint extends Object {
  // A number identifying this breakpoint to the user.
  int breakpointNumber;

  // Has this breakpoint been assigned to a specific program location?
  bool resolved;

  // Is this a breakpoint that was added synthetically as part of a step
  // OverAsyncSuspension resume command?
  bool isSyntheticAsyncContinuation [optional];

  // SourceLocation when breakpoint is resolved, UnresolvedSourceLocation
  // when a breakpoint is not resolved.
  SourceLocation|UnresolvedSourceLocation location;
}

A Breakpoint describes a debugger breakpoint.

A breakpoint is resolved when it has been assigned to a specific program location. A breakpoint my remain unresolved when it is in code which has not yet been compiled or in a library which has not been loaded (i.e. a deferred library).

Class

class @Class extends @Object {
  // The name of this class.
  string name;
}

@Class is a reference to a Class.

class Class extends Object {
  // The name of this class.
  string name;

  // The error which occurred during class finalization, if it exists.
  @Error error [optional];

  // Is this an abstract class?
  bool abstract;

  // Is this a const class?
  bool const;

  // The library which contains this class.
  @Library library;

  // The location of this class in the source code.
  SourceLocation location [optional];

  // The superclass of this class, if any.
  @Class super [optional];

  // The supertype for this class, if any.
  //
  // The value will be of the kind: Type.
  @Instance superType [optional];

  // A list of interface types for this class.
  //
  // The values will be of the kind: Type.
  @Instance[] interfaces;

  // The mixin type for this class, if any.
  //
  // The value will be of the kind: Type.
  @Instance mixin [optional];

  // A list of fields in this class. Does not include fields from
  // superclasses.
  @Field[] fields;

  // A list of functions in this class. Does not include functions
  // from superclasses.
  @Function[] functions;

  // A list of subclasses of this class.
  @Class[] subclasses;
}

A Class provides information about a Dart language class.

ClassList

class ClassList extends Response {
  @Class[] classes;
}

Code

class @Code extends @Object {
  // A name for this code object.
  string name;

  // What kind of code object is this?
  CodeKind kind;
}

@Code is a reference to a Code object.

class Code extends @Object {
  // A name for this code object.
  string name;

  // What kind of code object is this?
  CodeKind kind;
}

A Code object represents compiled code in the Dart VM.

CodeKind

enum CodeKind {
  Dart,
  Native,
  Stub,
  Tag,
  Collected
}

Context

class @Context extends @Object {
  // The number of variables in this context.
  int length;
}
class Context extends Object {
  // The number of variables in this context.
  int length;

  // The enclosing context for this context.
  Context parent [optional];

  // The variables in this context object.
  ContextElement[] variables;
}

A Context is a data structure which holds the captured variables for some closure.

ContextElement

class ContextElement {
  @Instance|Sentinel value;
}

Error

class @Error extends @Object {
  // What kind of error is this?
  ErrorKind kind;

  // A description of the error.
  string message;
}

@Error is a reference to an Error.

class Error extends Object {
  // What kind of error is this?
  ErrorKind kind;

  // A description of the error.
  string message;

  // If this error is due to an unhandled exception, this
  // is the exception thrown.
  @Instance exception [optional];

  // If this error is due to an unhandled exception, this
  // is the stacktrace object.
  @Instance stacktrace [optional];
}

An Error represents a Dart language level error. This is distinct from an rpc error.

ErrorKind

enum ErrorKind {
  // The isolate has encountered an unhandled Dart exception.
  UnhandledException,

  // The isolate has encountered a Dart language error in the program.
  LanguageError,

  // The isolate has encounted an internal error. These errors should be
  // reported as bugs.
  InternalError,

  // The isolate has been terminated by an external source.
  TerminationError
}

Event

class Event extends Response {
  // What kind of event is this?
  EventKind kind;

  // The isolate with which this event is associated.
  //
  // This is provided for all event kinds except for:
  //   VMUpdate
  @Isolate isolate [optional];

  // The vm with which this event is associated.
  //
  // This is provided for the event kind:
  //   VMUpdate
  @VM vm [optional];

  // The timestamp (in milliseconds since the epoch) associated with this event.
  // For some isolate pause events, the timestamp is from when the isolate was
  // paused. For other events, the timestamp is from when the event was created.
  int timestamp;

  // The breakpoint which was added, removed, or resolved.
  //
  // This is provided for the event kinds:
  //   PauseBreakpoint
  //   BreakpointAdded
  //   BreakpointRemoved
  //   BreakpointResolved
  Breakpoint breakpoint [optional];

  // The list of breakpoints at which we are currently paused
  // for a PauseBreakpoint event.
  //
  // This list may be empty. For example, while single-stepping, the
  // VM sends a PauseBreakpoint event with no breakpoints.
  //
  // If there is more than one breakpoint set at the program position,
  // then all of them will be provided.
  //
  // This is provided for the event kinds:
  //   PauseBreakpoint
  Breakpoint[] pauseBreakpoints [optional];

  // The top stack frame associated with this event, if applicable.
  //
  // This is provided for the event kinds:
  //   PauseBreakpoint
  //   PauseInterrupted
  //   PauseException
  //
  // For PauseInterrupted events, there will be no top frame if the
  // isolate is idle (waiting in the message loop).
  //
  // For the Resume event, the top frame is provided at
  // all times except for the initial resume event that is delivered
  // when an isolate begins execution.
  Frame topFrame [optional];

  // The exception associated with this event, if this is a
  // PauseException event.
  @Instance exception [optional];

  // An array of bytes, encoded as a base64 string.
  //
  // This is provided for the WriteEvent event.
  string bytes [optional];

  // The argument passed to dart:developer.inspect.
  //
  // This is provided for the Inspect event.
  @Instance inspectee [optional];

  // The RPC name of the extension that was added.
  //
  // This is provided for the ServiceExtensionAdded event.
  string extensionRPC [optional];

  // The extension event kind.
  //
  // This is provided for the Extension event.
  string extensionKind [optional];

  // The extension event data.
  //
  // This is provided for the Extension event.
  ExtensionData extensionData [optional];

  // An array of TimelineEvents
  //
  // This is provided for the TimelineEvents event.
  TimelineEvent[] timelineEvents [optional];

  // Is the isolate paused at an await, yield, or yield* statement?
  //
  // This is provided for the event kinds:
  //   PauseBreakpoint
  //   PauseInterrupted
  bool atAsyncSuspension [optional];

  // The status (success or failure) related to the event.
  // This is provided for the event kinds:
  //   IsolateReloaded
  //   IsolateSpawn
  string status [optional];
}

An Event is an asynchronous notification from the VM. It is delivered only when the client has subscribed to an event stream using the streamListen RPC.

For more information, see events.

EventKind

enum EventKind {
  // Notification that VM identifying information has changed. Currently used
  // to notify of changes to the VM debugging name via setVMName.
  VMUpdate,

  // Notification that a new isolate has started.
  IsolateStart,

  // Notification that an isolate is ready to run.
  IsolateRunnable,

  // Notification that an isolate has exited.
  IsolateExit,

  // Notification that isolate identifying information has changed.
  // Currently used to notify of changes to the isolate debugging name
  // via setName.
  IsolateUpdate,

  // Notification that an isolate has been reloaded.
  IsolateReload,

  // Notification that an extension RPC was registered on an isolate.
  ServiceExtensionAdded,

  // An isolate has paused at start, before executing code.
  PauseStart,

  // An isolate has paused at exit, before terminating.
  PauseExit,

  // An isolate has paused at a breakpoint or due to stepping.
  PauseBreakpoint,

  // An isolate has paused due to interruption via pause.
  PauseInterrupted,

  // An isolate has paused due to an exception.
  PauseException,

  // An isolate has paused after a service request.
  PausePostRequest,

  // An isolate has started or resumed execution.
  Resume,

  // Indicates an isolate is not yet runnable. Only appears in an Isolate's
  // pauseEvent. Never sent over a stream.
  None,

  // A breakpoint has been added for an isolate.
  BreakpointAdded,

  // An unresolved breakpoint has been resolved for an isolate.
  BreakpointResolved,

  // A breakpoint has been removed.
  BreakpointRemoved,

  // A garbage collection event.
  GC,

  // Notification of bytes written, for example, to stdout/stderr.
  WriteEvent,

  // Notification from dart:developer.inspect.
  Inspect,

  // Event from dart:developer.postEvent.
  Extension
}

Adding new values to EventKind is considered a backwards compatible change. Clients should ignore unrecognized events.

ExtensionData

class ExtensionData {
}

An ExtensionData is an arbitrary map that can have any contents.

Field

class @Field extends @Object {
  // The name of this field.
  string name;

  // The owner of this field, which can be either a Library or a
  // Class.
  @Object owner;

  // The declared type of this field.
  //
  // The value will always be of one of the kinds:
  // Type, TypeRef, TypeParameter, BoundedType.
  @Instance declaredType;

  // Is this field const?
  bool const;

  // Is this field final?
  bool final;

  // Is this field static?
  bool static;
}

An @Field is a reference to a Field.

class Field extends Object {
  // The name of this field.
  string name;

  // The owner of this field, which can be either a Library or a
  // Class.
  @Object owner;

  // The declared type of this field.
  //
  // The value will always be of one of the kinds:
  // Type, TypeRef, TypeParameter, BoundedType.
  @Instance declaredType;

  // Is this field const?
  bool const;

  // Is this field final?
  bool final;

  // Is this field static?
  bool static;

  // The value of this field, if the field is static.
  @Instance staticValue [optional];

  // The location of this field in the source code.
  SourceLocation location [optional];
}

A Field provides information about a Dart language field or variable.

Flag

class Flag {
  // The name of the flag.
  string name;

  // A description of the flag.
  string comment;

  // Has this flag been modified from its default setting?
  bool modified;

  // The value of this flag as a string.
  //
  // If this property is absent, then the value of the flag was NULL.
  string valueAsString [optional];
}

A Flag represents a single VM command line flag.

FlagList

class FlagList extends Response {
  // A list of all flags in the VM.
  Flag[] flags;
}

A FlagList represents the complete set of VM command line flags.

Frame

class Frame extends Response {
  int index;
  @Function function [optional];
  @Code code [optional];
  SourceLocation location [optional];
  BoundVariable[] vars [optional];
  FrameKind kind [optional];
}

Function

class @Function extends @Object {
  // The name of this function.
  string name;

  // The owner of this function, which can be a Library, Class, or a Function.
  @Library|@Class|@Function owner;

  // Is this function static?
  bool static;

  // Is this function const?
  bool const;
}

An @Function is a reference to a Function.

class Function extends Object {
  // The name of this function.
  string name;

  // The owner of this function, which can be a Library, Class, or a Function.
  @Library|@Class|@Function owner;

  // The location of this function in the source code.
  SourceLocation location [optional];

  // The compiled code associated with this function.
  @Code code [optional];
}

A Function represents a Dart language function.

Instance

class @Instance extends @Object {
  // What kind of instance is this?
  InstanceKind kind;

  // Instance references always include their class.
  @Class class;

  // The value of this instance as a string.
  //
  // Provided for the instance kinds:
  //   Null (null)
  //   Bool (true or false)
  //   Double (suitable for passing to Double.parse())
  //   Int (suitable for passing to int.parse())
  //   String (value may be truncated)
  //   Float32x4
  //   Float64x2
  //   Int32x4
  //   StackTrace
  string valueAsString [optional];

  // The valueAsString for String references may be truncated. If so,
  // this property is added with the value 'true'.
  //
  // New code should use 'length' and 'count' instead.
  bool valueAsStringIsTruncated [optional];

  // The length of a List or the number of associations in a Map or the
  // number of codeunits in a String.
  //
  // Provided for instance kinds:
  //   String
  //   List
  //   Map
  //   Uint8ClampedList
  //   Uint8List
  //   Uint16List
  //   Uint32List
  //   Uint64List
  //   Int8List
  //   Int16List
  //   Int32List
  //   Int64List
  //   Float32List
  //   Float64List
  //   Int32x4List
  //   Float32x4List
  //   Float64x2List
  int length [optional];

  // The name of a Type instance.
  //
  // Provided for instance kinds:
  //   Type
  string name [optional];

  // The corresponding Class if this Type has a resolved typeClass.
  //
  // Provided for instance kinds:
  //   Type
  @Class typeClass [optional];

  // The parameterized class of a type parameter:
  //
  // Provided for instance kinds:
  //   TypeParameter
  @Class parameterizedClass [optional];


  // The pattern of a RegExp instance.
  //
  // The pattern is always an instance of kind String.
  //
  // Provided for instance kinds:
  //   RegExp
  @Instance pattern [optional];
}

@Instance is a reference to an Instance.

class Instance extends Object {
  // What kind of instance is this?
  InstanceKind kind;

  // Instance references always include their class.
  @Class class;

  // The value of this instance as a string.
  //
  // Provided for the instance kinds:
  //   Bool (true or false)
  //   Double (suitable for passing to Double.parse())
  //   Int (suitable for passing to int.parse())
  //   String (value may be truncated)
  string valueAsString [optional];

  // The valueAsString for String references may be truncated. If so,
  // this property is added with the value 'true'.
  //
  // New code should use 'length' and 'count' instead.
  bool valueAsStringIsTruncated [optional];

  // The length of a List or the number of associations in a Map or the
  // number of codeunits in a String.
  //
  // Provided for instance kinds:
  //   String
  //   List
  //   Map
  //   Uint8ClampedList
  //   Uint8List
  //   Uint16List
  //   Uint32List
  //   Uint64List
  //   Int8List
  //   Int16List
  //   Int32List
  //   Int64List
  //   Float32List
  //   Float64List
  //   Int32x4List
  //   Float32x4List
  //   Float64x2List
  int length [optional];

  // The index of the first element or association or codeunit returned.
  // This is only provided when it is non-zero.
  //
  // Provided for instance kinds:
  //   String
  //   List
  //   Map
  //   Uint8ClampedList
  //   Uint8List
  //   Uint16List
  //   Uint32List
  //   Uint64List
  //   Int8List
  //   Int16List
  //   Int32List
  //   Int64List
  //   Float32List
  //   Float64List
  //   Int32x4List
  //   Float32x4List
  //   Float64x2List
  int offset [optional];

  // The number of elements or associations or codeunits returned.
  // This is only provided when it is less than length.
  //
  // Provided for instance kinds:
  //   String
  //   List
  //   Map
  //   Uint8ClampedList
  //   Uint8List
  //   Uint16List
  //   Uint32List
  //   Uint64List
  //   Int8List
  //   Int16List
  //   Int32List
  //   Int64List
  //   Float32List
  //   Float64List
  //   Int32x4List
  //   Float32x4List
  //   Float64x2List
  int count [optional];

  // The name of a Type instance.
  //
  // Provided for instance kinds:
  //   Type
  string name [optional];

  // The corresponding Class if this Type is canonical.
  //
  // Provided for instance kinds:
  //   Type
  @Class typeClass [optional];

  // The parameterized class of a type parameter:
  //
  // Provided for instance kinds:
  //   TypeParameter
  @Class parameterizedClass [optional];

  // The fields of this Instance.
  BoundField[] fields [optional];

  // The elements of a List instance.
  //
  // Provided for instance kinds:
  //   List
  (@Instance|Sentinel)[] elements [optional];

  // The elements of a Map instance.
  //
  // Provided for instance kinds:
  //   Map
  MapAssociation[] associations [optional];

  // The bytes of a TypedData instance.
  //
  // The data is provided as a Base64 encoded string.
  //
  // Provided for instance kinds:
  //   Uint8ClampedList
  //   Uint8List
  //   Uint16List
  //   Uint32List
  //   Uint64List
  //   Int8List
  //   Int16List
  //   Int32List
  //   Int64List
  //   Float32List
  //   Float64List
  //   Int32x4List
  //   Float32x4List
  //   Float64x2List
  string bytes [optional];

  // The function associated with a Closure instance.
  //
  // Provided for instance kinds:
  //   Closure
  @Function closureFunction [optional];

  // The context associated with a Closure instance.
  //
  // Provided for instance kinds:
  //   Closure
  @Context closureContext [optional];

  // The referent of a MirrorReference instance.
  //
  // Provided for instance kinds:
  //   MirrorReference
  @Instance mirrorReferent [optional];

  // The pattern of a RegExp instance.
  //
  // Provided for instance kinds:
  //   RegExp
  String pattern [optional];

  // Whether this regular expression is case sensitive.
  //
  // Provided for instance kinds:
  //   RegExp
  bool isCaseSensitive [optional];

  // Whether this regular expression matches multiple lines.
  //
  // Provided for instance kinds:
  //   RegExp
  bool isMultiLine [optional];

  // The key for a WeakProperty instance.
  //
  // Provided for instance kinds:
  //   WeakProperty
  @Instance propertyKey [optional];

  // The key for a WeakProperty instance.
  //
  // Provided for instance kinds:
  //   WeakProperty
  @Instance propertyValue [optional];

  // The type arguments for this type.
  //
  // Provided for instance kinds:
  //   Type
  @TypeArguments typeArguments [optional];

  // The index of a TypeParameter instance.
  //
  // Provided for instance kinds:
  //   TypeParameter
  int parameterIndex [optional];

  // The type bounded by a BoundedType instance
  // - or -
  // the referent of a TypeRef instance.
  //
  // The value will always be of one of the kinds:
  // Type, TypeRef, TypeParameter, BoundedType.
  //
  // Provided for instance kinds:
  //   BoundedType
  //   TypeRef
  @Instance targetType [optional];

  // The bound of a TypeParameter or BoundedType.
  //
  // The value will always be of one of the kinds:
  // Type, TypeRef, TypeParameter, BoundedType.
  //
  // Provided for instance kinds:
  //   BoundedType
  //   TypeParameter
  @Instance bound [optional];
}

An Instance represents an instance of the Dart language class Object.

InstanceKind

enum InstanceKind {
  // A general instance of the Dart class Object.
  PlainInstance,

  // null instance.
  Null,

  // true or false.
  Bool,

  // An instance of the Dart class double.
  Double,

  // An instance of the Dart class int.
  Int,

  // An instance of the Dart class String.
  String,

  // An instance of the built-in VM List implementation. User-defined
  // Lists will be PlainInstance.
  List,

  // An instance of the built-in VM Map implementation. User-defined
  // Maps will be PlainInstance.
  Map,

  // Vector instance kinds.
  Float32x4,
  Float64x2,
  Int32x4

  // An instance of the built-in VM TypedData implementations. User-defined
  // TypedDatas will be PlainInstance.
  Uint8ClampedList,
  Uint8List,
  Uint16List,
  Uint32List,
  Uint64List,
  Int8List,
  Int16List,
  Int32List,
  Int64List,
  Float32List,
  Float64List,
  Int32x4List,
  Float32x4List,
  Float64x2List,

  // An instance of the Dart class StackTrace.
  StackTrace,

  // An instance of the built-in VM Closure implementation. User-defined
  // Closures will be PlainInstance.
  Closure,

  // An instance of the Dart class MirrorReference.
  MirrorReference,

  // An instance of the Dart class RegExp.
  RegExp,

  // An instance of the Dart class WeakProperty.
  WeakProperty,

  // An instance of the Dart class Type.
  Type,

  // An instance of the Dart class TypeParameter.
  TypeParameter,

  // An instance of the Dart class TypeRef.
  TypeRef,

  // An instance of the Dart class BoundedType.
  BoundedType,
}

Adding new values to InstanceKind is considered a backwards compatible change. Clients should treat unrecognized instance kinds as PlainInstance.

Isolate

class @Isolate extends Response {
  // The id which is passed to the getIsolate RPC to load this isolate.
  string id;

  // A numeric id for this isolate, represented as a string. Unique.
  string number;

  // A name identifying this isolate. Not guaranteed to be unique.
  string name;
}

@Isolate is a reference to an Isolate object.

class Isolate extends Response {
  // The id which is passed to the getIsolate RPC to reload this
  // isolate.
  string id;

  // A numeric id for this isolate, represented as a string. Unique.
  string number;

  // A name identifying this isolate. Not guaranteed to be unique.
  string name;

  // The time that the VM started in milliseconds since the epoch.
  //
  // Suitable to pass to DateTime.fromMillisecondsSinceEpoch.
  int startTime;

  // Is the isolate in a runnable state?
  bool runnable;

  // The number of live ports for this isolate.
  int livePorts;

  // Will this isolate pause when exiting?
  bool pauseOnExit;

  // The last pause event delivered to the isolate. If the isolate is
  // running, this will be a resume event.
  Event pauseEvent;

  // The root library for this isolate.
  //
  // Guaranteed to be initialized when the IsolateRunnable event fires.
  @Library rootLib [optional];

  // A list of all libraries for this isolate.
  //
  // Guaranteed to be initialized when the IsolateRunnable event fires.
  @Library[] libraries;

  // A list of all breakpoints for this isolate.
  Breakpoint[] breakpoints;

  // The error that is causing this isolate to exit, if applicable.
  Error error [optional];

  // The current pause on exception mode for this isolate.
  ExceptionPauseMode exceptionPauseMode;

  // The list of service extension RPCs that are registered for this isolate,
  // if any.
  string[] extensionRPCs [optional];
}

An Isolate object provides information about one isolate in the VM.

Library

class @Library extends @Object {
  // The name of this library.
  string name;

  // The uri of this library.
  string uri;
}

@Library is a reference to a Library.

class Library extends Object {
  // The name of this library.
  string name;

  // The uri of this library.
  string uri;

  // Is this library debuggable? Default true.
  bool debuggable;

  // A list of the imports for this library.
  LibraryDependency[] dependencies;

  // A list of the scripts which constitute this library.
  @Script[] scripts;

  // A list of the top-level variables in this library.
  @Field[] variables;

  // A list of the top-level functions in this library.
  @Function[] functions;

  // A list of all classes in this library.
  @Class[] classes;
}

A Library provides information about a Dart language library.

See setLibraryDebuggable.

LibraryDependency

class LibraryDependency {
  // Is this dependency an import (rather than an export)?
  bool isImport;

  // Is this dependency deferred?
  bool isDeferred;

  // The prefix of an 'as' import, or null.
  String prefix;

  // The library being imported or exported.
  @Library target;
}

A LibraryDependency provides information about an import or export.

MapAssociation

class MapAssociation {
  @Instance|Sentinel key;
  @Instance|Sentinel value;
}

Message

class Message extends Response {
  // The index in the isolate's message queue. The 0th message being the next
  // message to be processed.
  int index;

  // An advisory name describing this message.
  string name;

  // An instance id for the decoded message. This id can be passed to other
  // RPCs, for example, getObject or evaluate.
  string messageObjectId;

  // The size (bytes) of the encoded message.
  int size;

  // A reference to the function that will be invoked to handle this message.
  @Function handler [optional];

  // The source location of handler.
  SourceLocation location [optional];
}

A Message provides information about a pending isolate message and the function that will be invoked to handle it.

Null

class @Null extends @Instance {
  // Always 'null'.
  string valueAsString;
}

@Null is a reference to an a Null.

class Null extends Instance {
  // Always 'null'.
  string valueAsString;
}

A Null object represents the Dart language value null.

Object

class @Object extends Response {
  // A unique identifier for an Object. Passed to the
  // getObject RPC to load this Object.
  string id;
}

@Object is a reference to a Object.

class Object extends Response {
  // A unique identifier for an Object. Passed to the
  // getObject RPC to reload this Object.
  //
  // Some objects may get a new id when they are reloaded.
  string id;

  // If an object is allocated in the Dart heap, it will have
  // a corresponding class object.
  //
  // The class of a non-instance is not a Dart class, but is instead
  // an internal vm object.
  //
  // Moving an Object into or out of the heap is considered a
  // backwards compatible change for types other than Instance.
  @Class class [optional];

  // The size of this object in the heap.
  //
  // If an object is not heap-allocated, then this field is omitted.
  //
  // Note that the size can be zero for some objects. In the current
  // VM implementation, this occurs for small integers, which are
  // stored entirely within their object pointers.
  int size [optional];
}

An Object is a persistent object that is owned by some isolate.

ReloadReport

class ReloadReport extends Response {
  // Did the reload succeed or fail?
  bool success;
}

Response

class Response {
  // Every response returned by the VM Service has the
  // type property. This allows the client distinguish
  // between different kinds of responses.
  string type;
}

Every non-error response returned by the Service Protocol extends Response. By using the type property, the client can determine which type of response has been provided.

Sentinel

class Sentinel extends Response {
  // What kind of sentinel is this?
  SentinelKind kind;

  // A reasonable string representation of this sentinel.
  string valueAsString;
}

A Sentinel is used to indicate that the normal response is not available.

We use a Sentinel instead of an error for these cases because they do not represent a problematic condition. They are normal.

SentinelKind

enum SentinelKind {
  // Indicates that the object referred to has been collected by the GC.
  Collected,

  // Indicates that an object id has expired.
  Expired,

  // Indicates that a variable or field has not been initialized.
  NotInitialized,

  // Indicates that a variable or field is in the process of being initialized.
  BeingInitialized,

  // Indicates that a variable has been eliminated by the optimizing compiler.
  OptimizedOut,

  // Reserved for future use.
  Free,
}

A SentinelKind is used to distinguish different kinds of Sentinel objects.

Adding new values to SentinelKind is considered a backwards compatible change. Clients must handle this gracefully.

FrameKind

enum FrameKind {
  Regular,
  AsyncCausal,
  AsyncSuspensionMarker,
  AsyncActivation
}

A FrameKind is used to distinguish different kinds of Frame objects.

Script

class @Script extends @Object {
  // The uri from which this script was loaded.
  string uri;
}

@Script is a reference to a Script.

class Script extends Object {
  // The uri from which this script was loaded.
  string uri;

  // The library which owns this script.
  @Library library;

  // The source code for this script. For certain built-in scripts,
  // this may be reconstructed without source comments.
  string source;

  // A table encoding a mapping from token position to line and column.
  int[][] tokenPosTable;
}

A Script provides information about a Dart language script.

The tokenPosTable is an array of int arrays. Each subarray consists of a line number followed by (tokenPos, columnNumber) pairs:

[lineNumber, (tokenPos, columnNumber)*]

The tokenPos is an arbitrary integer value that is used to represent a location in the source code. A tokenPos value is not meaningful in itself and code should not rely on the exact values returned.

For example, a tokenPosTable with the value...

[[1, 100, 5, 101, 8],[2, 102, 7]]

...encodes the mapping:

tokenPos line column
100 1 5
101 1 8
102 2 7

SourceLocation

class SourceLocation extends Response {
  // The script containing the source location.
  @Script script;

  // The first token of the location.
  int tokenPos;

  // The last token of the location if this is a range.
  int endTokenPos [optional];
}

The SourceLocation class is used to designate a position or range in some script.

SourceReport

class SourceReport extends Response {
  // A list of ranges in the program source.  These ranges correspond
  // to ranges of executable code in the user's program (functions,
  // methods, constructors, etc.)
  //
  // Note that ranges may nest in other ranges, in the case of nested
  // functions.
  //
  // Note that ranges may be duplicated, in the case of mixins.
  SourceReportRange[] ranges;

  // A list of scripts, referenced by index in the report's ranges.
  ScriptRef[] scripts;
}

The SourceReport class represents a set of reports tied to source locations in an isolate.

SourceReportCoverage

class SourceReportCoverage {
  // A list of token positions in a SourceReportRange which have been
  // executed.  The list is sorted.
  int[] hits;

  // A list of token positions in a SourceReportRange which have not been
  // executed.  The list is sorted.
  int[] misses;
}

The SourceReportCoverage class represents coverage information for one SourceReportRange.

Note that SourceReportCoverage does not extend Response and therefore will not contain a type property.

SourceReportKind

enum SourceReportKind {
  // Used to request a code coverage information.
  Coverage,

  // Used to request a list of token positions of possible breakpoints.
  PossibleBreakpoints
}

SourceReportRange

class SourceReportRange {
  // An index into the script table of the SourceReport, indicating
  // which script contains this range of code.
  int scriptIndex;

  // The token position at which this range begins.
  int startPos;

  // The token position at which this range ends.  Inclusive.
  int endPos;

  // Has this range been compiled by the Dart VM?
  bool compiled;

  // The error while attempting to compile this range, if this
  // report was generated with forceCompile=true.
  @Error error [optional];

  // Code coverage information for this range.  Provided only when the
  // Coverage report has been requested and the range has been
  // compiled.
  SourceReportCoverage coverage [optional];

  // Possible breakpoint information for this range, represented as a
  // sorted list of token positions.  Provided only when the when the
  // PossibleBreakpoint report has been requested and the range has been
  // compiled.
  int[] possibleBreakpoints [optional];
}

The SourceReportRange class represents a range of executable code (function, method, constructor, etc) in the running program. It is part of a SourceReport.

Note that SourceReportRange does not extend Response and therefore will not contain a type property.

Stack

class Stack extends Response {
  Frame[] frames;
  Frame[] asyncCausalFrames [optional];
  Frame[] awaiterFrames [optional];
  Message[] messages;
}

ExceptionPauseMode

enum ExceptionPauseMode {
  None,
  Unhandled,
  All,
}

An ExceptionPauseMode indicates how the isolate pauses when an exception is thrown.

StepOption

enum StepOption {
  Into,
  Over,
  OverAsyncSuspension,
  Out,
  Rewind
}

A StepOption indicates which form of stepping is requested in a resume RPC.

Success

class Success extends Response {
}

The Success type is used to indicate that an operation completed successfully.

TimelineEvent

class TimelineEvent {
}

An TimelineEvent is an arbitrary map that contains a Trace Event Format event.

TypeArguments

class @TypeArguments extends @Object {
  // A name for this type argument list.
  string name;
}

@TypeArguments is a reference to a TypeArguments object.

class TypeArguments extends Object {
  // A name for this type argument list.
  string name;

  // A list of types.
  //
  // The value will always be one of the kinds:
  // Type, TypeRef, TypeParameter, BoundedType.
  @Instance[] types;
}

A TypeArguments object represents the type argument vector for some instantiated generic type.

UnresolvedSourceLocation

class UnresolvedSourceLocation extends Response {
  // The script containing the source location if the script has been loaded.
  @Script script [optional];

  // The uri of the script containing the source location if the script
  // has yet to be loaded.
  string scriptUri [optional];

  // An approximate token position for the source location. This may
  // change when the location is resolved.
  int tokenPos [optional];

  // An approximate line number for the source location. This may
  // change when the location is resolved.
  int line [optional];

  // An approximate column number for the source location. This may
  // change when the location is resolved.
  int column [optional];

}

The UnresolvedSourceLocation class is used to refer to an unresolved breakpoint location. As such, it is meant to approximate the final location of the breakpoint but it is not exact.

Either the script or the scriptUri field will be present.

Either the tokenPos or the line field will be present.

The column field will only be present when the breakpoint was specified with a specific column number.

Version

class Version extends Response {
  // The major version number is incremented when the protocol is changed
  // in a potentially incompatible way.
  int major;

  // The minor version number is incremented when the protocol is changed
  // in a backwards compatible way.
  int minor;
}

See Versioning.

VM

class @VM extends Response {
  // A name identifying this vm. Not guaranteed to be unique.
  string name;
}

@VM is a reference to a VM object.

class VM extends Response {
  // Word length on target architecture (e.g. 32, 64).
  int architectureBits;

  // The CPU we are generating code for.
  string targetCPU;

  // The CPU we are actually running on.
  string hostCPU;

  // The Dart VM version string.
  string version;

  // The process id for the VM.
  int pid;

  // The time that the VM started in milliseconds since the epoch.
  //
  // Suitable to pass to DateTime.fromMillisecondsSinceEpoch.
  int startTime;

  // A list of isolates running in the VM.
  @Isolate[] isolates;
}

Revision History

version comments
1.0 initial revision
2.0 Describe protocol version 2.0.
3.0 Describe protocol version 3.0. Added UnresolvedSourceLocation. Added Sentinel 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. Added ServiceExtensionAdded event.
3.1 Add the getSourceReport RPC. The getObject RPC now accepts offset and count for string objects. String objects now contain length, offset, and count properties.
3.2 Isolate objects now include the runnable bit and many debugger related RPCs will return an error if executed on an isolate before it is runnable.
3.3 Pause event now indicates if the isolate is paused at an await, yield, or yield* suspension point via the 'atAsyncSuspension' field. Resume command now supports the step parameter 'OverAsyncSuspension'. A Breakpoint added synthetically by an 'OverAsyncSuspension' resume command identifies itself as such via the 'isSyntheticAsyncContinuation' field.
3.4 Add the superType and mixin fields to Class. Added new pause event 'None'.
3.5 Add the error field to SourceReportRange. Clarify definition of token position. Add "Isolate must be paused" error code.
3.6 Add 'scopeStartTokenPos', 'scopeEndTokenPos', and 'declarationTokenPos' to BoundVariable. Add 'PausePostRequest' event kind. Add 'Rewind' StepOption. Add error code 107 (isolate cannot resume). Add 'reloadSources' RPC and related error codes. Add optional parameter 'scope' to 'evaluate' and 'evaluateInFrame'.
3.7 Add 'setFlag'.