blob: 2714021d8ff8755423cd1d5e5c3e8c008d6f3062 [file] [log] [blame]
// Copyright (c) 2020, the Dart project authors. Please see the AUTHORS file
// for details. All rights reserved. Use of this source code is governed by a
// BSD-style license that can be found in the LICENSE file.
import 'package:json_rpc_2/json_rpc_2.dart' as json_rpc;
import 'client.dart';
import 'constants.dart';
import 'dds_impl.dart';
/// This file contains functionality used to track the running state of
/// all isolates in a given Dart process.
/// [_RunningIsolate] is a representation of a single live isolate and contains
/// running state information for that isolate. In addition, approvals from
/// clients used to synchronize isolate resuming across multiple clients are
/// tracked in this class.
/// The [IsolateManager] keeps track of all the isolates in the
/// target process and handles isolate lifecycle events including:
/// - Startup
/// - Shutdown
/// - Pauses
/// The [IsolateManager] also handles the `resume` RPC, which checks the
/// resume approvals in the target [_RunningIsolate] to determine if the
/// isolate should be resumed or wait for additional approvals to be granted.
enum _IsolateState {
class _RunningIsolate {
// State setters.
void pausedOnExit() => _state = _IsolateState.pauseExit;
void pausedOnStart() => _state = _IsolateState.pauseStart;
void pausedPostRequest() => _state = _IsolateState.pausePostRequest;
void resumed() => running();
void running() => _state = _IsolateState.running;
void started() => _state = _IsolateState.start;
/// Resumes the isolate if all clients which need to approve a resume have
/// done so. Called when the last client of a given name disconnects or
/// changes name to ensure we don't deadlock waiting for approval to resume
/// from a disconnected client.
Future<void> maybeResumeAfterClientChange(String clientName) async {
// Remove approvals from the disconnected client.
if (shouldResume()) {
await'resume', {
'isolateId': id,
/// Returns true if this isolate should resume given its client approvals
/// state.
/// If `resumingClient` is provided, it will be added to the set of clients
/// which have provided approval to resume this isolate. If not provided,
/// the existing approvals state will be examined to see if the isolate
/// should resume due to a client disconnect or name change.
bool shouldResume({DartDevelopmentServiceClient resumingClient}) {
if (resumingClient != null) {
// Mark approval by the client.
final requiredClientApprovals = <String>{};
final permissions =;
// Determine which clients require approval for this pause type.
permissions.forEach((name, clientNamePermissions) {
if (clientNamePermissions.permissionsMask & _isolateStateMask != 0) {
// We require at least a single client to resume, even if that client
// doesn't require resume approval.
if (_resumeApprovalsByName.isEmpty) {
return false;
// If all the required approvals are present, we should resume.
return _resumeApprovalsByName.containsAll(requiredClientApprovals);
/// Resets the internal resume approvals state.
/// Should always be called after an isolate is resumed.
void clearResumeApprovals() => _resumeApprovalsByName.clear();
int get _isolateStateMask => isolateStateToMaskMapping[_state] ?? 0;
static const isolateStateToMaskMapping = {
_IsolateState.pauseStart: PauseTypeMasks.pauseOnStartMask,
_IsolateState.pausePostRequest: PauseTypeMasks.pauseOnReloadMask,
_IsolateState.pauseExit: PauseTypeMasks.pauseOnExitMask,
final IsolateManager isolateManager;
final String name;
final String id;
final Set<String> _resumeApprovalsByName = {};
_IsolateState _state;
class IsolateManager {
/// Handles state changes for isolates.
void handleIsolateEvent(json_rpc.Parameters parameters) {
final event = parameters['event'];
final eventKind = event['kind'].asString;
// There's no interesting information about isolate state associated with
// and IsolateSpawn event.
if (eventKind == ServiceEvents.isolateSpawn) {
final isolateData = event['isolate'];
final id = isolateData['id'].asString;
final name = isolateData['name'].asString;
_updateIsolateState(id, name, eventKind);
void _updateIsolateState(String id, String name, String eventKind) {
switch (eventKind) {
case ServiceEvents.isolateStart:
isolateStarted(id, name);
case ServiceEvents.isolateExit:
final isolate = isolates[id];
switch (eventKind) {
case ServiceEvents.pauseExit:
case ServiceEvents.pausePostRequest:
case ServiceEvents.pauseStart:
case ServiceEvents.resume:
/// Initializes the set of running isolates.
Future<void> initialize() async {
if (_initialized) {
final vm = await dds.vmServiceClient.sendRequest('getVM');
final List<Map> isolateRefs = vm['isolates'].cast<Map<String, dynamic>>();
// Check the pause event for each isolate to determine whether or not the
// isolate is already paused.
for (final isolateRef in isolateRefs) {
final id = isolateRef['id'];
final isolate = await dds.vmServiceClient.sendRequest('getIsolate', {
'isolateId': id,
final name = isolate['name'];
if (isolate.containsKey('pauseEvent')) {
isolates[id] = _RunningIsolate(this, id, name);
final eventKind = isolate['pauseEvent']['kind'];
_updateIsolateState(id, name, eventKind);
} else {
// If the isolate doesn't have a pauseEvent, assume it's running.
isolateStarted(id, name);
_initialized = true;
/// Initializes state for a newly started isolate.
void isolateStarted(String id, String name) {
final isolate = _RunningIsolate(this, id, name);
isolates[id] = isolate;
/// Cleans up state for an isolate that has exited.
void isolateExited(String id) {
/// Handles `resume` RPC requests. If the 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.
Future<Map<String, dynamic>> resumeIsolate(
DartDevelopmentServiceClient client,
json_rpc.Parameters parameters,
) async {
final isolateId = parameters['isolateId'].asString;
final isolate = isolates[isolateId];
if (isolate == null) {
return RPCResponses.collectedSentinel;
if (isolate.shouldResume(resumingClient: client)) {
return await _sendResumeRequest(isolateId, parameters);
return RPCResponses.success;
/// Forwards a `resume` request to the VM service.
Future<Map<String, dynamic>> _sendResumeRequest(
String isolateId,
json_rpc.Parameters parameters,
) async {
final step = parameters['step'].asStringOr(null);
final frameIndex = parameters['frameIndex'].asIntOr(null);
final resumeResult = await dds.vmServiceClient.sendRequest('resume', {
'isolateId': isolateId,
if (step != null) 'step': step,
if (frameIndex != null) 'frameIndex': frameIndex,
return resumeResult;
bool _initialized = false;
final DartDevelopmentServiceImpl dds;
final Map<String, _RunningIsolate> isolates = {};