This change reworks the client resume permissions API to make it easier for clients to deal with user provided `--pause-isolates-on-start` and `--pause-isolates-on-exit` flags. `requireUserPermissionToResume` should be called by the tool that launches the Dart process to indicate whether or not the user provided `--pause-isolates-on-{start,exit}`. The default behavior is to assume that a tool set these flags for its own use (e.g., resetting breakpoints after a hot restart in Flutter), where isolates will resume immediately after each client that has indicated interest in that pause event has invoked `readyToResume`. If a user provided one of the previously mentioned flags, isolates will not immediately resume after each relevant client has invoked `readyToResume`. Instead, a call to `resume()` must be made to indicate the user has triggered the resume request instead of tooling. If the user permissions to resume are changed while the isolate is paused and all relevant clients have invoked `readyToResume`, the isolate will automatically resume if the user no longer requires us to wait for a user resume. `resume()` now also acts as a "force resume", bypassing any required permissions set by tooling. This behavior change is breaking, so the DDS protocol version is being bumped to 2.0. `package:dds_service_extensions` has also been updated to include the following DDS RPCs: - `requireUserPermissionToResume` - `readyToResume` Change-Id: Id5f0806b3c56507d39eb00b6305b8896bab13ae7 Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/357420 Reviewed-by: Elliott Brooks <elliottbrooks@google.com> Commit-Queue: Ben Konyi <bkonyi@google.com>
12 KiB
Dart Development Service Protocol 2.0
This document describes version 2.0 of the Dart Development Service Protocol. This protocol is an extension of the Dart VM Service Protocol and implements it in it's entirety. For details on the VM Service Protocol, see the Dart VM Service Protocol Specification.
The Service Protocol uses JSON-RPC 2.0.
Table of Contents
RPCs, Requests, and Responses
See the corresponding section in the VM Service protocol here.
Events
See the corresponding section in the VM Service protocol here.
Binary Events
See the corresponding section in the VM Service protocol here.
Types
See the corresponding section in the VM Service protocol here.
IDs and Names
See the corresponding section in the VM Service protocol here.
Streams
For a list of core VM service streams, see streamListen.
DDS will keep a history of events on certain streams and send historical events when a client first subscribes to a stream with history. These streams currently consist of the following:
Logging
Stdout
Stderr
Extension
In addition, subscribing to the Service
stream will result in a ServiceRegistered
event being sent to the subscribing client for each existing service extension.
From protocol version 1.4, custom streams of any name can be listened to via DDS.
Public RPCs
The DDS Protocol supports all public RPCs defined in the VM Service protocol.
getAvailableCachedCpuSamples
AvailableCachedCpuSamples getAvailableCachedCpuSamples();
The getAvailableCachedCpuSamples RPC is used to determine which caches of CPU samples are available. Caches are associated with individual UserTag names and are specified when DDS is started via the cachedUserTags parameter.
See AvailableCachedCpuSamples.
getCachedCpuSamples
CachedCpuSamples getCachedCpuSamples(string isolateId, string userTag);
The getCachedCpuSamples RPC is used to retrieve a cache of CPU samples collected under a UserTag with name userTag.
See CachedCpuSamples.
getClientName
ClientName getClientName()
The getClientName RPC is used to retrieve the name associated with the currently connected VM service client. If no name was previously set through the setClientName RPC, a default name will be returned.
See ClientName
getDartDevelopmentServiceVersion
Version getDartDevelopmentServiceVersion()
The getDartDevelopmentServiceVersion RPC is used to determine what version of the Dart Development Service Protocol is served by a DDS instance.
See Version.
getLogHistorySize
Size getLogHistorySize()
The getLogHistorySize RPC is used to retrieve the current size of the log history buffer. If the returned Size is zero, then log history is disabled.
See Size.
getPerfettoVMTimelineWithCpuSamples
PerfettoTimeline getPerfettoVMTimelineWithCpuSamples(int timeOriginMicros [optional],
int timeExtentMicros [optional])
The getPerfettoVMTimelineWithCpuSamples RPC functions nearly identically to
the VM Service Protocol's getPerfettoVMTimeline RPC, except the trace
field
of the PerfettoTimeline
response returned by this RPC will be a Base64 string
encoding a Perfetto-format trace that includes not only all timeline events
in the specified time range, but also all CPU samples from all isolates in the
specified time range.
See the documentation of getPerfettoVMTimeline and getPerfettoCpuSamples in the Dart VM Service Protocol Specification.
getStreamHistory
StreamHistory getStreamHistory(string streamId)
The getStreamHistory RPC is used to retrieve historical events for streams which support event history (see Streams for a list of supported streams).
See StreamHistory.
postEvent
void postEvent(String stream, String eventKind, Map eventData)
The postEvent RPC is used to send events to custom Event streams.
readyToResume
Success readyToResume(string isolateId)
The readyToResume RPC indicates to DDS that the current client is ready to resume the isolate.
If the current client requires that approval be given before resuming an isolate, this method will:
- Update the approval state for the isolate.
- Resume the isolate if approval has been given by all clients which require approval.
Returns a collected sentinel if the isolate no longer exists.
See Success.
requirePermissionToResume
Success requirePermissionToResume(bool onPauseStart [optional],
bool onPauseReload[optional],
bool onPauseExit [optional])
The requirePermissionToResume RPC is used to change the pause/resume behavior of isolates by providing a way for the VM service to wait for approval to resume from some set of clients. This is useful for clients which want to perform some operation on an isolate after a pause without it being resumed by another client. These clients should invoke readyToResume instead of resume to indicate to DDS that they have finished their work and the isolate can be resumed.
If the onPauseStart parameter is true
, isolates will not resume after pausing
on start until the client sends a resume
request and all other clients which
need to provide resume approval for this pause type have done so.
If the onPauseReload parameter is true
, isolates will not resume after pausing
after a reload until the client sends a resume
request and all other clients
which need to provide resume approval for this pause type have done so.
If the onPauseExit parameter is true
, isolates will not resume after pausing
on exit until the client sends a resume
request and all other clients which
need to provide resume approval for this pause type have done so.
Important Notes:
- All clients with the same client name share resume permissions. Only a single client of a given name is required to provide resume approval.
- When a client requiring approval disconnects from the service, a paused isolate may resume if all other clients requiring resume approval have already given approval. In the case that no other client requires resume approval for the current pause event, the isolate will be resumed if at least one other client has attempted to resume the isolate.
- Resume permission behavior can be bypassed using the [VmService.resume] RPC, which is treated as a user-initiated resume that force resumes the isolate. Tooling relying on resume permissions should use readyToResume instead of resume to avoid force resuming the isolate.
See Success.
requireUserPermissionToResume
Success requireUserPermissionToResume(bool onPauseStart [optional],
bool onPauseExit [optional])
The requireUserPermissionToResume RPC notifies DDS if it should wait for a resume request to resume isolates paused on start or exit.
This RPC should only be invoked by tooling which launched the target Dart process and knows if the user indicated they wanted isolates paused on start or exit.
See Success.
setClientName
Success setClientName(string name)
The setClientName RPC is used to set a name to be associated with the currently connected VM service client. If the name parameter is a non-empty string, name will become the new name associated with the client. If name is an empty string, the client's name will be reset to its default name.
See Success.
setLogHistorySize
Success setLogHistorySize(int size)
The setLogHistorySize RPC is used to set the size of the ring buffer used for caching a limited set of historical log messages. If size is 0, logging history will be disabled. The maximum history size is 100,000 messages, with the default set to 10,000 messages.
See Success.
Public Types
The DDS Protocol supports all public types defined in the VM Service protocol.
AvailableCachedCpuSamples
class AvailableCachedCpuSamples extends Response {
// A list of UserTag names associated with CPU sample caches.
string[] cacheNames;
}
A collection of [UserTag] names associated with caches of CPU samples.
See getAvailableCachedCpuSamples.
CachedCpuSamples
class CachedCpuSamples extends CpuSamples {
// The name of the UserTag associated with this cache of samples.
string userTag;
// Provided if the CPU sample cache has filled and older samples have been
// dropped.
bool truncated [optional];
}
An extension of CpuSamples which represents a set of cached samples, associated with a particular [UserTag] name.
See getCachedCpuSamples.
ClientName
class ClientName extends Response {
// The name of the currently connected VM service client.
string name;
}
See getClientName and setClientName.
Size
class Size extends Response {
int size;
}
A simple object representing a size response.
StreamHistory
class StreamHistory extends Response {
// A list of historical Events for a stream.
List<Event> history;
}
See getStreamHistory.
Revision History
version | comments |
---|---|
1.0 | Initial revision |
1.1 | Added getDartDevelopmentServiceVersion RPC. |
1.2 | Added getStreamHistory RPC. |
1.3 | Added getAvailableCachedCpuSamples and getCachedCpuSamples RPCs. |
1.4 | Added the ability to subscribe to custom streams (which can be specified when calling dart:developer 's postEvent ). |
1.5 | Added getPerfettoCpuSamples RPC. |
1.6 | Added postEvent RPC. |