Please post feedback to the observatory-discuss group
This document describes of version 3.45 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.
Service Protocol Extension provides similar ways to communicate with the VM except these may be only accessible through some libraries.
The Service Protocol uses JSON-RPC 2.0.
Table of Contents
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 |
| 114 | Invalid timeline request | The timeline related request could not be completed due to the current configuration |
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.
Some events are associated with bulk binary data. These events are delivered as WebSocket binary frames instead of text frames. A binary event's metadata should be interpreted as UTF-8 encoded JSON, with the same properties as described above for ordinary events.
type BinaryEvent {
dataOffset : uint32,
metadata : uint8[dataOffset-4],
data : uint8[],
}
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": ...
...
}
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.
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.
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.
The VM service allows for an extended feature set via the Dart Development Service (DDS) that forward all core VM service RPCs described in this document to the true VM service.
When DDS connects to the VM service, the VM service enters single client mode and will no longer accept incoming web socket connections, instead forwarding the web socket connection request to DDS. If DDS disconnects from the VM service, the VM service will once again start accepting incoming web socket connections.
The VM service forwards the web socket connection by issuing a redirect
Middleware like the Dart Development Service have the option of providing functionality which builds on or extends the VM service protocol. Middleware which offer protocol extensions should intercept calls to getSupportedProtocols and modify the resulting ProtocolList to include their own Protocol information before responding to the requesting client.
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 RPC error response.
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.
Breakpoint|Sentinel 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) RPC error code is returned.
Note that breakpoints are added and removed on a per-isolate basis.
If isolateId refers to an isolate which has exited, then the Collected Sentinel is returned.
See Breakpoint.
Breakpoint|Sentinel 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) RPC error code is returned.
Note that breakpoints are added and removed on a per-isolate basis.
If isolateId refers to an isolate which has exited, then the Collected Sentinel is returned.
See Breakpoint.
Breakpoint|Sentinel 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) RPC error code is returned.
If isolateId refers to an isolate which has exited, then the Collected Sentinel is returned.
See Breakpoint.
Note that breakpoints are added and removed on a per-isolate basis.
Success|Sentinel clearCpuSamples(string isolateId)
Clears all CPU profiling samples.
If isolateId refers to an isolate which has exited, then the Collected Sentinel is returned.
See Success.
Success clearVMTimeline()
Clears all VM timeline events.
See Success.
@Instance|@Error|Sentinel invoke(string isolateId,
string targetId,
string selector,
string[] argumentIds,
bool disableBreakpoints [optional])
The invoke RPC is used to perform regular method invocation on some receiver, as if by dart:mirror's ObjectMirror.invoke. Note this does not provide a way to perform getter, setter or constructor invocation.
targetId may refer to a Library, Class, or Instance.
Each elements of argumentId may refer to an Instance.
If disableBreakpoints is provided and set to true, any breakpoints hit as a result of this invocation are ignored, including pauses resulting from a call to debugger() from dart:developer. Defaults to false if not provided.
If targetId or any element of argumentIds is a temporary id which has expired, then the Expired Sentinel is returned.
If targetId or any element of argumentIds refers to an object which has been collected by the VM's garbage collector, then the Collected Sentinel is returned.
If isolateId refers to an isolate which has exited, then the Collected Sentinel is returned.
If invocation triggers a failed compilation then RPC error 113 “Expression compilation error” is returned.
If a runtime error occurs while evaluating the invocation, an @Error reference will be returned.
If the invocation is evaluated successfully, an @Instance reference will be returned.
@Instance|@Error|Sentinel evaluate(string isolateId,
string targetId,
string expression,
map<string,string> scope [optional],
bool disableBreakpoints [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 isolateId refers to an isolate which has exited, 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 disableBreakpoints is provided and set to true, any breakpoints hit as a result of this evaluation are ignored. Defaults to false if not provided.
If the expression fails 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.
@Instance|@Error|Sentinel evaluateInFrame(string isolateId,
int frameIndex,
string expression,
map<string,string> scope [optional],
bool disableBreakpoints [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 disableBreakpoints is provided and set to true, any breakpoints hit as a result of this evaluation are ignored. Defaults to false if not provided.
If the expression fails 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.
If isolateId refers to an isolate which has exited, then the Collected Sentinel is returned.
AllocationProfile|Sentinel getAllocationProfile(string isolateId,
bool reset [optional],
bool gc [optional])
The getAllocationProfile RPC is used to retrieve allocation information for a given isolate.
If reset is provided and is set to true, the allocation accumulators will be reset before collecting allocation information.
If gc is provided and is set to true, a garbage collection will be attempted before collecting allocation information. There is no guarantee that a garbage collection will be actually be performed.
If isolateId refers to an isolate which has exited, then the Collected Sentinel is returned.
CpuSamples getAllocationTraces(string isolateId, int timeOriginMicros [optional], int timeExtentMicros [optional], string classId [optional])
The getAllocationTraces RPC allows for the retrieval of allocation traces for objects of a specific set of types (see setTraceClassAllocation). Only samples collected in the time range [timeOriginMicros, timeOriginMicros + timeExtentMicros] will be reported.
If classId is provided, only traces for allocations with the matching classId will be reported.
If the profiler is disabled, an RPC error response will be returned.
If isolateId refers to an isolate which has exited, then the Collected Sentinel is returned.
See CpuSamples.
ClassList|Sentinel getClassList(string isolateId)
The getClassList RPC is used to retrieve a ClassList containing all classes for an isolate based on the isolate's isolateId.
If isolateId refers to an isolate which has exited, then the Collected Sentinel is returned.
See ClassList.
CpuSamples|Sentinel getCpuSamples(string isolateId,
int timeOriginMicros,
int timeExtentMicros)
The getCpuSamples RPC is used to retrieve samples collected by the CPU profiler. Only samples collected in the time range [timeOriginMicros, timeOriginMicros + timeExtentMicros] will be reported.
If the profiler is disabled, an RPC error response will be returned.
If isolateId refers to an isolate which has exited, then the Collected Sentinel is returned.
See CpuSamples.
FlagList getFlagList()
The getFlagList RPC returns a list of all command line flags in the VM along with their current values.
See FlagList.
InboundReferences|Sentinel getInboundReferences(string isolateId,
string targetId,
int limit)
Returns a set of inbound references to the object specified by targetId. Up to limit references will be returned.
The order of the references is undefined (i.e., not related to allocation order) and unstable (i.e., multiple invocations of this method against the same object can give different answers even if no Dart code has executed between the invocations).
The references may include multiple objectIds that designate the same object.
The references may include objects that are unreachable but have not yet been garbage collected.
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 isolateId refers to an isolate which has exited, then the Collected Sentinel is returned.
See InboundReferences.
InstanceSet|Sentinel getInstances(string isolateId,
string objectId,
int limit)
The getInstances RPC is used to retrieve a set of instances which are of a specific class. This does not include instances of subclasses of the given class.
The order of the instances is undefined (i.e., not related to allocation order) and unstable (i.e., multiple invocations of this method against the same class can give different answers even if no Dart code has executed between the invocations).
The set of instances may include objects that are unreachable but have not yet been garbage collected.
objectId is the ID of the Class to retrieve instances for. objectId must be the ID of a Class, otherwise an RPC error is returned.
limit is the maximum number of instances to be returned.
If isolateId refers to an isolate which has exited, then the Collected Sentinel is returned.
See InstanceSet.
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.
IsolateGroup|Sentinel getIsolateGroup(string isolateGroupId)
The getIsolateGroup RPC is used to lookup an IsolateGroup object by its id.
If isolateGroupId refers to an isolate group which has exited, then the Expired Sentinel is returned.
IsolateGroup id is an opaque identifier that can be fetched from an IsolateGroup. List of active IsolateGroup's, for example, is available on VM object.
See IsolateGroup, VM.
MemoryUsage|Sentinel getMemoryUsage(string isolateId)
The getMemoryUsage RPC is used to lookup an isolate's memory usage statistics by its id.
If isolateId refers to an isolate which has exited, then the Collected Sentinel is returned.
See Isolate.
MemoryUsage|Sentinel getIsolateGroupMemoryUsage(string isolateGroupId)
The getIsolateGroupMemoryUsage RPC is used to lookup an isolate group's memory usage statistics by its id.
If isolateGroupId refers to an isolate group which has exited, then the Expired Sentinel is returned.
See IsolateGroup.
ScriptList|Sentinel getScripts(string isolateId)
The getScripts RPC is used to retrieve a ScriptList containing all scripts for an isolate based on the isolate's isolateId.
If isolateId refers to an isolate which has exited, then the Collected Sentinel is returned.
See ScriptList.
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 isolateId refers to an isolate which has exited, then the Collected 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.
PortList getPorts(string isolateId)
The getPorts RPC is used to retrieve the list of ReceivePort instances for a given isolate.
See PortList.
RetainingPath|Sentinel getRetainingPath(string isolateId,
string targetId,
int limit)
The getRetainingPath RPC is used to lookup a path from an object specified by targetId to a GC root (i.e., the object which is preventing this object from being garbage collected).
If isolateId refers to an isolate which has exited, then the Collected Sentinel is returned.
If targetId refers to a heap object which has been collected by the VM's garbage collector, then the Collected Sentinel is returned.
If targetId 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 RetainingPath will be returned.
The limit parameter specifies the maximum path length to be reported as part of the retaining path. If a path is longer than limit, it will be truncated at the root end of the path.
See RetainingPath.
ProcessMemoryUsage getProcessMemoryUsage()
Returns a description of major uses of memory known to the VM.
Adding or removing buckets is considered a backwards-compatible change for the purposes of versioning. A client must gracefully handle the removal or addition of any bucket.
Stack|Sentinel getStack(string isolateId, int limit [optional])
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.
If limit is provided, up to limit frames from the top of the stack will be returned. If the stack depth is smaller than limit the entire stack is returned. Note: this limit also applies to the asyncCausalFrames and awaiterFrames stack representations in the Stack response.
If isolateId refers to an isolate which has exited, then the Collected Sentinel is returned.
See Stack.
ProtocolList getSupportedProtocols()
The getSupportedProtocols RPC is used to determine which protocols are supported by the current server.
The result of this call should be intercepted by any middleware that extends the core VM service protocol and should add its own protocol to the list of protocols before forwarding the response to the client.
See ProtocolList.
SourceReport|Sentinel 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.
If isolateId refers to an isolate which has exited, then the Collected Sentinel is returned.
See SourceReport.
Version getVersion()
The getVersion RPC is used to determine what version of the Service Protocol is served by a VM.
See Version.
VM getVM()
The getVM RPC returns global information about a Dart virtual machine.
See VM.
Timeline getVMTimeline(int timeOriginMicros [optional],
int timeExtentMicros [optional])
The getVMTimeline RPC is used to retrieve an object which contains VM timeline events.
The timeOriginMicros parameter is the beginning of the time range used to filter timeline events. It uses the same monotonic clock as dart:developer‘s Timeline.now and the VM embedding API’s Dart_TimelineGetMicros. See getVMTimelineMicros for access to this clock through the service protocol.
The timeExtentMicros parameter specifies how large the time range used to filter timeline events should be.
For example, given timeOriginMicros and timeExtentMicros, only timeline events from the following time range will be returned: (timeOriginMicros, timeOriginMicros + timeExtentMicros).
If getVMTimeline is invoked while the current recorder is one of Fuchsia or Macos or Systrace, an RPC error with error code 114, invalid timeline request, will be returned as timeline events are handled by the OS in these modes.
TimelineFlags getVMTimelineFlags()
The getVMTimelineFlags RPC returns information about the current VM timeline configuration.
To change which timeline streams are currently enabled, see setVMTimelineFlags.
See TimelineFlags.
Timestamp getVMTimelineMicros()
The getVMTimelineMicros RPC returns the current time stamp from the clock used by the timeline, similar to Timeline.now in dart:developer and Dart_TimelineGetMicros in the VM embedding API.
See Timestamp and getVMTimeline.
Success|Sentinel 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.
If isolateId refers to an isolate which has exited, then the Collected Sentinel is returned.
See Success.
Success|Sentinel 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.
If isolateId refers to an isolate which has exited, then the Collected Sentinel is returned.
See Success.
Success registerService(string service, string alias)
Registers a service that can be invoked by other VM service clients, where service is the name of the service to advertise and alias is an alternative name for the registered service.
Requests made to the new service will be forwarded to the client which originally registered the service.
See Success.
ReloadReport|Sentinel 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.
If isolateId refers to an isolate which has exited, then the Collected Sentinel is returned.
Success|Sentinel 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.
If isolateId refers to an isolate which has exited, then the Collected Sentinel is returned.
See Success.
Success|Sentinel requestHeapSnapshot(string isolateId)
Requests a dump of the Dart heap of the given isolate.
This method immediately returns success. The VM will then begin delivering binary events on the HeapSnapshot event stream. The binary data in these events, when concatenated together, conforms to the SnapshotGraph type. The splitting of the SnapshotGraph into events can happen at any byte offset.
If isolateId refers to an isolate which has exited, then the Collected Sentinel is returned.
Success|Sentinel 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.
If isolateId refers to an isolate which has exited, then the Collected Sentinel is returned.
See Success, StepOption.
Breakpoint setBreakpointState(string isolateId,
string breakpointId,
bool enable)
The setBreakpointState RPC allows for breakpoints to be enabled or disabled, without requiring for the breakpoint to be completely removed.
If isolateId refers to an isolate which has exited, then the Collected Sentinel is returned.
The returned Breakpoint is the updated breakpoint with its new values.
See Breakpoint.
Success|Sentinel 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 |
If isolateId refers to an isolate which has exited, then the Collected Sentinel is returned.
Success|Error 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:
Notes:
profile_period can be set to a minimum value of 50. Attempting to set profile_period to a lower value will result in a value of 50 being set.profiler will enable or disable the profiler depending on the provided value. If set to false when the profiler is already running, the profiler will be stopped but may not free its sample buffer depending on platform limitations.See Success.
Success|Sentinel 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.
If isolateId refers to an isolate which has exited, then the Collected Sentinel is returned.
See Success.
Success|Sentinel setName(string isolateId,
string name)
The setName RPC is used to change the debugging name for an isolate.
If isolateId refers to an isolate which has exited, then the Collected Sentinel is returned.
See Success.
Success|Sentinel setTraceClassAllocation(string isolateId, string classId, bool enable)
The setTraceClassAllocation RPC allows for enabling or disabling allocation tracing for a specific type of object. Allocation traces can be retrieved with the getAllocationTraces RPC.
If enable is true, allocations of objects of the class represented by classId will be traced.
If isolateId refers to an isolate which has exited, then the Collected Sentinel is returned.
See Success.
Success setVMName(string name)
The setVMName RPC is used to change the debugging name for the vm.
See Success.
Success setVMTimelineFlags(string[] recordedStreams)
The setVMTimelineFlags RPC is used to set which timeline streams are enabled.
The recordedStreams parameter is the list of all timeline streams which are to be enabled. Streams not explicitly specified will be disabled. Invalid stream names are ignored.
A TimelineStreamSubscriptionsUpdate event is sent on the Timeline stream as a result of invoking this RPC.
To get the list of currently enabled timeline streams, see getVMTimelineFlags.
See Success.
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) RPC error code is returned.
See Success.
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 already subscribed to the stream, the 103 (Stream already subscribed) RPC error code is returned.
The streamId parameter may have the following published values:
| streamId | event types provided |
|---|---|
| VM | VMUpdate, VMFlagUpdate |
| Isolate | IsolateStart, IsolateRunnable, IsolateExit, IsolateUpdate, IsolateReload, ServiceExtensionAdded |
| Debug | PauseStart, PauseExit, PauseBreakpoint, PauseInterrupted, PauseException, PausePostRequest, Resume, BreakpointAdded, BreakpointResolved, BreakpointRemoved, BreakpointUpdated, Inspect, None |
| GC | GC |
| Extension | Extension |
| Timeline | TimelineEvents, TimelineStreamsSubscriptionUpdate |
| Logging | Logging |
| Service | ServiceRegistered, ServiceUnregistered |
| HeapSnapshot | HeapSnapshot |
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.
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.
class AllocationProfile extends Response {
// Allocation information for all class types.
ClassHeapStats[] members;
// Information about memory usage for the isolate.
MemoryUsage memoryUsage;
// The timestamp of the last accumulator reset.
//
// If the accumulators have not been reset, this field is not present.
int dateLastAccumulatorReset [optional];
// The timestamp of the last manually triggered GC.
//
// If a GC has not been triggered manually, this field is not present.
int dateLastServiceGC [optional];
}
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.
class BoundVariable extends Response {
string name;
@Instance|@TypeArguments|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.
class Breakpoint extends Object {
// A number identifying this breakpoint to the user.
int breakpointNumber;
// Is this breakpoint enabled?
bool enabled;
// 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 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;
// Are allocations of this class being traced?
bool traceAllocations;
// 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.
class ClassHeapStats extends Response {
// The class for which this memory information is associated.
@Class class;
// The number of bytes allocated for instances of class since the
// accumulator was last reset.
int accumulatedSize;
// The number of bytes currently allocated for instances of class.
int bytesCurrent;
// The number of instances of class which have been allocated since
// the accumulator was last reset.
int instancesAccumulated;
// The number of instances of class which are currently alive.
int instancesCurrent;
}
class ClassList extends Response {
@Class[] classes;
}
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.
enum CodeKind {
Dart,
Native,
Stub,
Tag,
Collected
}
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.
class ContextElement {
@Instance|Sentinel value;
}
class CpuSamples extends Response {
// The sampling rate for the profiler in microseconds.
int samplePeriod;
// The maximum possible stack depth for samples.
int maxStackDepth;
// The number of samples returned.
int sampleCount;
// The timespan the set of returned samples covers, in microseconds (deprecated).
//
// Note: this property is deprecated and will always return -1. Use `timeExtentMicros`
// instead.
int timeSpan;
// The start of the period of time in which the returned samples were
// collected.
int timeOriginMicros;
// The duration of time covered by the returned samples.
int timeExtentMicros;
// The process ID for the VM.
int pid;
// A list of functions seen in the relevant samples. These references can be
// looked up using the indicies provided in a `CpuSample` `stack` to determine
// which function was on the stack.
ProfileFunction[] functions;
// A list of samples collected in the range
// `[timeOriginMicros, timeOriginMicros + timeExtentMicros]`
CpuSample[] samples;
}
See getCpuSamples and CpuSample.
class CpuSample {
// The thread ID representing the thread on which this sample was collected.
int tid;
// The time this sample was collected in microseconds.
int timestamp;
// The name of VM tag set when this sample was collected. Omitted if the VM
// tag for the sample is not considered valid.
string vmTag [optional];
// The name of the User tag set when this sample was collected. Omitted if no
// User tag was set when this sample was collected.
string userTag [optional];
// Provided and set to true if the sample's stack was truncated. This can
// happen if the stack is deeper than the `stackDepth` in the `CpuSamples`
// response.
bool truncated [optional];
// The call stack at the time this sample was collected. The stack is to be
// interpreted as top to bottom. Each element in this array is a key into the
// `functions` array in `CpuSamples`.
//
// Example:
//
// `functions[stack[0]] = @Function(bar())`
// `functions[stack[1]] = @Function(foo())`
// `functions[stack[2]] = @Function(main())`
int[] stack;
// The identityHashCode assigned to the allocated object. This hash
// code is the same as the hash code provided in HeapSnapshot. Provided for
// CpuSample instances returned from a getAllocationTraces().
int identityHashCode [optional];
// Matches the index of a class in HeapSnapshot.classes. Provided for
// CpuSample instances returned from a getAllocationTraces().
int classId [optional];
}
See getCpuSamples and CpuSamples.
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.
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 encountered an internal error. These errors should be
// reported as bugs.
InternalError,
// The isolate has been terminated by an external source.
TerminationError
}
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, VMFlagUpdate
@Isolate isolate [optional];
// The vm with which this event is associated.
//
// This is provided for the event kind:
// VMUpdate, VMFlagUpdate
@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
// BreakpointUpdated
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];
// The new set of recorded timeline streams.
//
// This is provided for the TimelineStreamSubscriptionsUpdate event.
string[] updatedStreams [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
string status [optional];
// LogRecord data.
//
// This is provided for the Logging event.
LogRecord logRecord [optional];
// The service identifier.
//
// This is provided for the event kinds:
// ServiceRegistered
// ServiceUnregistered
String service [optional];
// The RPC method that should be used to invoke the service.
//
// This is provided for the event kinds:
// ServiceRegistered
// ServiceUnregistered
String method [optional];
// The alias of the registered service.
//
// This is provided for the event kinds:
// ServiceRegistered
String alias [optional];
// The name of the changed flag.
//
// This is provided for the event kinds:
// VMFlagUpdate
String flag [optional];
// The new value of the changed flag.
//
// This is provided for the event kinds:
// VMFlagUpdate
String newValue [optional];
// Specifies whether this event is the last of a group of events.
//
// This is provided for the event kinds:
// HeapSnapshot
bool last [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.
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 VM flag has been changed via the service protocol.
VMFlagUpdate,
// 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 breakpoint has been updated.
BreakpointUpdated,
// 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,
// Event from dart:developer.log.
Logging,
// A block of timeline events has been completed.
//
// This service event is not sent for individual timeline events. It is
// subject to buffering, so the most recent timeline events may never be
// included in any TimelineEvents event if no timeline events occur later to
// complete the block.
TimelineEvents,
// The set of active timeline streams was changed via `setVMTimelineFlags`.
TimelineStreamSubscriptionsUpdate,
// Notification that a Service has been registered into the Service Protocol
// from another client.
ServiceRegistered,
// Notification that a Service has been removed from the Service Protocol
// from another client.
ServiceUnregistered,
}
Adding new values to EventKind is considered a backwards compatible change. Clients should ignore unrecognized events.
class ExtensionData {
}
An ExtensionData is an arbitrary map that can have any contents.
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. If uninitialized,
// this will take the value of an uninitialized Sentinel.
@Instance|Sentinel 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.
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.
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.
class Frame extends Response {
int index;
@Function function [optional];
@Code code [optional];
SourceLocation location [optional];
BoundVariable[] vars [optional];
FrameKind kind [optional];
}
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;
// Is this function static?
bool static;
// Is this function const?
bool const;
// 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.
class @Instance extends @Object {
// What kind of instance is this?
InstanceKind kind;
// The identityHashCode assigned to the allocated object. This hash
// code is the same as the hash code provided in HeapSnapshot and
// CpuSample's returned by getAllocationTraces().
int identityHashCode;
// 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];
// 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 port ID for a ReceivePort.
//
// Provided for instance kinds:
// ReceivePort
int portId [optional];
// The stack trace associated with the allocation of a ReceivePort.
//
// Provided for instance kinds:
// ReceivePort
@Instance allocationLocation [optional];
// A name associated with a ReceivePort used for debugging purposes.
//
// Provided for instance kinds:
// ReceivePort
string debugName [optional];
}
@Instance is a reference to an Instance.
class Instance extends Object {
// What kind of instance is this?
InstanceKind kind;
// The identityHashCode assigned to the allocated object. This hash
// code is the same as the hash code provided in HeapSnapshot and
// CpuSample's returned by getAllocationTraces().
int identityHashCode;
// 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)
// 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 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 referent of a MirrorReference instance.
//
// Provided for instance kinds:
// MirrorReference
@Instance mirrorReferent [optional];
// The pattern of a RegExp instance.
//
// Provided for instance kinds:
// RegExp
@Instance pattern [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];
// 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];
// The port ID for a ReceivePort.
//
// Provided for instance kinds:
// ReceivePort
int portId [optional];
// The stack trace associated with the allocation of a ReceivePort.
//
// Provided for instance kinds:
// ReceivePort
@Instance allocationLocation [optional];
// A name associated with a ReceivePort used for debugging purposes.
//
// Provided for instance kinds:
// ReceivePort
string debugName [optional];
}
An Instance represents an instance of the Dart language class Object.
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,
// An instance of the Dart class ReceivePort.
ReceivePort,
}
Adding new values to InstanceKind is considered a backwards compatible change. Clients should treat unrecognized instance kinds as PlainInstance.
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;
// Specifies whether the isolate was spawned by the VM or embedder for
// internal use. If `false`, this isolate is likely running user code.
bool isSystemIsolate;
}
@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;
// Specifies whether the isolate was spawned by the VM or embedder for
// internal use. If `false`, this isolate is likely running user code.
bool isSystemIsolate;
// The list of isolate flags provided to this isolate. See Dart_IsolateFlags
// in dart_api.h for the list of accepted isolate flags.
IsolateFlag[] isolateFlags;
// 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.
class IsolateFlag {
// The name of the flag.
string name;
// The value of this flag as a string.
string valueAsString;
}
Represents the value of a single isolate flag. See Isolate.
class @IsolateGroup extends Response {
// The id which is passed to the getIsolateGroup RPC to load this isolate group.
string id;
// A numeric id for this isolate group, represented as a string. Unique.
string number;
// A name identifying this isolate group. Not guaranteed to be unique.
string name;
// Specifies whether the isolate group was spawned by the VM or embedder for
// internal use. If `false`, this isolate group is likely running user code.
bool isSystemIsolateGroup;
}
@IsolateGroup is a reference to an IsolateGroup object.
class IsolateGroup 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;
// Specifies whether the isolate group was spawned by the VM or embedder for
// internal use. If `false`, this isolate group is likely running user code.
bool isSystemIsolateGroup;
// A list of all isolates in this isolate group.
@Isolate[] isolates;
}
An Isolate object provides information about one isolate in the VM.
class InboundReferences extends Response {
// An array of inbound references to an object.
InboundReference[] references;
}
See getInboundReferences.
class InboundReference {
// The object holding the inbound reference.
@Object source;
// If source is a List, parentListIndex is the index of the inbound reference.
int parentListIndex [optional];
// If source is a field of an object, parentField is the field containing the
// inbound reference.
@Field parentField [optional];
}
See getInboundReferences.
class InstanceSet extends Response {
// The number of instances of the requested type currently allocated.
int totalCount;
// An array of instances of the requested type.
@Object[] instances;
}
See getInstances.
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.
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.
class LogRecord extends Response {
// The log message.
@Instance message;
// The timestamp.
int time;
// The severity level (a value between 0 and 2000).
//
// See the package:logging `Level` class for an overview of the possible
// values.
int level;
// A monotonically increasing sequence number.
int sequenceNumber;
// The name of the source of the log message.
@Instance loggerName;
// The zone where the log was emitted.
@Instance zone;
// An error object associated with this log event.
@Instance error;
// A stack trace associated with this log event.
@Instance stackTrace;
}
class MapAssociation {
@Instance|Sentinel key;
@Instance|Sentinel value;
}
class MemoryUsage extends Response {
// The amount of non-Dart memory that is retained by Dart objects. For
// example, memory associated with Dart objects through APIs such as
// Dart_NewFinalizableHandle, Dart_NewWeakPersistentHandle and
// Dart_NewExternalTypedData. This usage is only as accurate as the values
// supplied to these APIs from the VM embedder or native extensions. This
// external memory applies GC pressure, but is separate from heapUsage and
// heapCapacity.
int externalUsage;
// The total capacity of the heap in bytes. This is the amount of memory used
// by the Dart heap from the perspective of the operating system.
int heapCapacity;
// The current heap memory usage in bytes. Heap usage is always less than or
// equal to the heap capacity.
int heapUsage;
}
A MemoryUsage object provides heap usage information for a specific isolate at a given point in time.
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.
class NativeFunction {
// The name of the native function this object represents.
string name;
}
A NativeFunction object is used to represent native functions in profiler samples. See CpuSamples;
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.
class @Object extends Response {
// A unique identifier for an Object. Passed to the
// getObject RPC to load this Object.
string id;
// Provided and set to true if the id of an Object is fixed. If true, the id
// of an Object is guaranteed not to change or expire. The object may, however,
// still be _Collected_.
bool fixedId [optional];
}
@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;
// Provided and set to true if the id of an Object is fixed. If true, the id
// of an Object is guaranteed not to change or expire. The object may, however,
// still be _Collected_.
bool fixedId [optional];
// 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.
class PortList extends Response {
@Instance[] ports;
}
A PortList contains a list of ports associated with some isolate.
See getPort.
class ProfileFunction {
// The kind of function this object represents.
string kind;
// The number of times function appeared on the stack during sampling events.
int inclusiveTicks;
// The number of times function appeared on the top of the stack during
// sampling events.
int exclusiveTicks;
// The resolved URL for the script containing function.
string resolvedUrl;
// The function captured during profiling.
(@Function|NativeFunction) function;
}
A ProfileFunction contains profiling information about a Dart or native function.
See CpuSamples.
class ProtocolList extends Response {
// A list of supported protocols provided by this service.
Protocol[] protocols;
}
A ProtocolList contains a list of all protocols supported by the service instance.
See Protocol and getSupportedProtocols.
class Protocol {
// The name of the supported protocol.
string protocolName;
// The major revision of the protocol.
int major;
// The minor revision of the protocol.
int minor;
}
class ProcessMemoryUsage extends Response {
ProcessMemoryItem root;
}
class ProcessMemoryItem {
// A short name for this bucket of memory.
string name;
// A longer description for this item.
string description;
// The amount of memory in bytes.
// This is a retained size, not a shallow size. That is, it includes the size
// of children.
int size;
// Subdivisons of this bucket of memory.
ProcessMemoryItem[] children;
}
class ReloadReport extends Response {
// Did the reload succeed or fail?
bool success;
}
class RetainingObject {
// An object that is part of a retaining path.
@Object value;
// The offset of the retaining object in a containing list.
int parentListIndex [optional];
// The key mapping to the retaining object in a containing map.
@Object parentMapKey [optional];
// The name of the field containing the retaining object within an object.
string parentField [optional];
}
See RetainingPath.
class RetainingPath extends Response {
// The length of the retaining path.
int length;
// The type of GC root which is holding a reference to the specified object.
// Possible values include:
// * class table
// * local handle
// * persistent handle
// * stack
// * user global
// * weak persistent handle
// * unknown
string gcRootType;
// The chain of objects which make up the retaining path.
RetainingObject[] elements;
}
See getRetainingPath.
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.
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.
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.
enum FrameKind {
Regular,
AsyncCausal,
AsyncSuspensionMarker,
AsyncActivation
}
A FrameKind is used to distinguish different kinds of Frame objects.
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;
int lineOffset [optional];
int columnOffset [optional];
// The source code for this script. This can be null for certain built-in
// scripts.
string source [optional];
// A table encoding a mapping from token position to line and column. This
// field is null if sources aren't available.
int[][] tokenPosTable [optional];
}
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 |
class ScriptList extends Response {
@Script[] scripts;
}
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.
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.
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.
enum SourceReportKind {
// Used to request a code coverage information.
Coverage,
// Used to request a list of token positions of possible breakpoints.
PossibleBreakpoints
}
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.
class Stack extends Response {
// A list of frames that make up the synchronous stack, rooted at the message
// loop (i.e., the frames since the last asynchronous gap or the isolate's
// entrypoint).
Frame[] frames;
// A list of frames representing the asynchronous path. Comparable to
// `awaiterFrames`, if provided, although some frames may be different.
Frame[] asyncCausalFrames [optional];
// A list of frames representing the asynchronous path. Comparable to
// `asyncCausalFrames`, if provided, although some frames may be different.
Frame[] awaiterFrames [optional];
// A list of messages in the isolate's message queue.
Message[] messages;
// Specifies whether or not this stack is complete or has been artificially
// truncated.
bool truncated;
}
The Stack class represents the various components of a Dart stack trace for a given isolate.
See getStack.
enum ExceptionPauseMode {
None,
Unhandled,
All,
}
An ExceptionPauseMode indicates how the isolate pauses when an exception is thrown.
enum StepOption {
Into,
Over,
OverAsyncSuspension,
Out,
Rewind
}
A StepOption indicates which form of stepping is requested in a resume RPC.
class Success extends Response {
}
The Success type is used to indicate that an operation completed successfully.
class Timeline extends Response {
// A list of timeline events. No order is guaranteed for these events; in particular, these events may be unordered with respect to their timestamps.
TimelineEvent[] traceEvents;
// The start of the period of time in which traceEvents were collected.
int timeOriginMicros;
// The duration of time covered by the timeline.
int timeExtentMicros;
}
class TimelineEvent {
}
An TimelineEvent is an arbitrary map that contains a Trace Event Format event.
class TimelineFlags extends Response {
// The name of the recorder currently in use. Recorder types include, but are
// not limited to: Callback, Endless, Fuchsia, Macos, Ring, Startup, and
// Systrace.
// Set to "null" if no recorder is currently set.
string recorderName;
// The list of all available timeline streams.
string[] availableStreams;
// The list of timeline streams that are currently enabled.
string[] recordedStreams;
}
class Timestamp extends Response {
// A timestamp in microseconds since epoch.
int timestamp;
}
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.
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.
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.
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 {
// A name identifying this vm. Not guaranteed to be unique.
string name;
// Word length on target architecture (e.g. 32, 64).
int architectureBits;
// The CPU we are actually running on.
string hostCPU;
// The operating system we are running on.
string operatingSystem;
// The CPU we are generating code for.
string targetCPU;
// 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;
// A list of isolate groups running in the VM.
@IsolateGroup[] isolateGroups;
// A list of system isolates running in the VM.
@Isolate[] systemIsolates;
// A list of isolate groups which contain system isolates running in the VM.
@IsolateGroup[] systemIsolateGroups;
}
| 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. |
| 3.8 | Add kill. |
| 3.9 | Changed numbers for errors related to service extensions. |
| 3.10 | Add invoke. |
| 3.11 | Rename invoke parameter receiverId to targetId. |
| 3.12 | Add getScripts RPC and ScriptList object. |
| 3.13 | Class mixin field now properly set for kernel transformed mixin applications. |
| 3.14 | Flag profile_period can now be set at runtime, allowing for the profiler sample rate to be changed while the program is running. |
| 3.15 | Added disableBreakpoints parameter to invoke, evaluate, and evaluateInFrame. |
| 3.16 | Add getMemoryUsage RPC and MemoryUsage object. |
| 3.17 | Add Logging event kind and the LogRecord class. |
| 3.18 | Add getAllocationProfile RPC and AllocationProfile and ClassHeapStats objects. |
| 3.19 | Add clearVMTimeline, getVMTimeline, getVMTimelineFlags, setVMTimelineFlags, Timeline, and TimelineFlags. |
| 3.20 | Add getInstances RPC and InstanceSet object. |
| 3.21 | Add getVMTimelineMicros RPC and Timestamp object. |
| 3.22 | Add registerService RPC, Service stream, and ServiceRegistered and ServiceUnregistered event kinds. |
| 3.23 | Add VMFlagUpdate event kind to the VM stream. |
| 3.24 | Add operatingSystem property to VM object. |
| 3.25 | Add getInboundReferences, getRetainingPath RPCs, and InboundReferences, InboundReference, RetainingPath, and RetainingObject objects. |
| 3.26 | Add requestHeapSnapshot. |
| 3.27 | Add clearCpuSamples, getCpuSamples RPCs and CpuSamples, CpuSample objects. |
| 3.28 | TODO(aam): document changes from 3.28 |
| 3.29 | Add getClientName, setClientName, requireResumeApproval |
| 3.30 | Updated return types of RPCs which require an isolateId to allow for Sentinel results if the target isolate has shutdown. |
| 3.31 | Added single client mode, which allows for the Dart Development Service (DDS) to become the sole client of the VM service. |
| 3.32 | Added getClassList RPC and ClassList object. |
| 3.33 | Added deprecation notice for getClientName, setClientName, requireResumeApproval, and ClientName. These RPCs are moving to the DDS protocol and will be removed in v4.0 of the VM service protocol. |
| 3.34 | Added TimelineStreamSubscriptionsUpdate event which is sent when setVMTimelineFlags is invoked. |
| 3.35 | Added getSupportedProtocols RPC and ProtocolList, Protocol objects. |
| 3.36 | Added getProcessMemoryUsage RPC and ProcessMemoryUsage and ProcessMemoryItem objects. |
| 3.37 | Added getWebSocketTarget RPC and WebSocketTarget object. |
| 3.38 | Added isSystemIsolate property to @Isolate and Isolate, isSystemIsolateGroup property to @IsolateGroup and IsolateGroup, and properties systemIsolates and systemIsolateGroups to VM. |
| 3.39 | Removed the following deprecated RPCs and objects: getClientName, getWebSocketTarget, setClientName, requireResumeApproval, ClientName, and WebSocketTarget. |
| 3.40 | Added IsolateFlag object and isolateFlags property to Isolate. |
| 3.41 | Added PortList object, ReceivePort InstanceKind, and getPorts RPC. |
| 3.42 | Added limit optional parameter to getStack RPC. |
| 3.43 | Updated heap snapshot format to include identity hash codes. Added getAllocationTraces and setTraceClassAllocation RPCs, updated CpuSample to include identityHashCode and classId properties, updated Class to include traceAllocations property. |
| 3.44 | Added identityHashCode property to @Instance and Instance. |
| 3.45 | Added setBreakpointState RPC and BreakpointUpdated event kind. |