[VM/Service] Add getQueuedMicrotasks RPC

TEST=pkg/vm_service/test/get_queued_microtasks_rpc_test

CoreLibraryReviewExempt: This CL does not include any core library API
changes, only VM Service implementation changes within
sdk/lib/vmservice/.
Change-Id: Ie5488f498e4d0f3d201e3f31423fd5029b74a726
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/425160
Commit-Queue: Derek Xu <[email protected]>
Reviewed-by: Ben Konyi <[email protected]>

Author: derekxu16

pkg/dds/lib/src/rpc_error_codes.dart

@@ -43,6 +43,7 @@ abstract class RpcErrorCodes {
   static const kExpressionCompilationError = 113;
 
   // static const kInvalidTimelineRequest = 114;
+  // static const kCannotGetQueuedMicrotasks = 115;
   static const kCustomStreamDoesNotExist = 130;
   static const kCoreStreamNotAllowed = 131;
 

pkg/pkg.status

@@ -145,6 +145,7 @@ vm_service/test/get_allocation_traces_test: SkipByDesign # Debugger is disabled
 vm_service/test/get_instances_as_*: SkipByDesign # Debugger is disabled in AOT mode
 vm_service/test/get_instances_rpc_test: SkipByDesign # Debugger is disabled in AOT mode.
 vm_service/test/get_object_rpc_test: SkipByDesign # Debugger is disabled in AOT mode.
+vm_service/test/get_queued_microtasks_rpc_test: SkipByDesign # In AOT mode, the debugger is disabled, and there's no other way to pause the testee at a point when the microtask queue is non-empty.
 vm_service/test/get_source_report_const_coverage_test: SkipByDesign # Debugger is disabled in AOT mode.
 vm_service/test/get_source_report_test: SkipByDesign # Debugger is disabled in AOT mode.
 vm_service/test/get_source_report_with_mixin_test: SkipByDesign # Debugger is disabled in AOT mode.

pkg/vm_service/CHANGELOG.md

@@ -1,8 +1,11 @@
-## 15.0.1
-- Update to version `4.17` of the spec.
+## 15.0.1-wip
+- Update to version `4.19` of the spec.
 - Add `Timer` stream.
 - Add `TimerSignificantlyOverdue` event kind.
 - Add `details` property to `Event`.
+- Add `getQueuedMicrotasks` RPC.
+- Add `Microtask` and `QueuedMicrotasks` types.
+- Add `RPCErrorKind.kCannotGetQueuedMicrotasks`.
 
 ## 15.0.0
 - Update type of `CodeRef.function` from `FuncRef` to `dynamic` to allow for `NativeFunction`

pkg/vm_service/java/.gitignore

@@ -35,6 +35,7 @@ src/org/dartlang/vm/service/consumer/PerfettoTimelineConsumer.java
 src/org/dartlang/vm/service/consumer/PortListConsumer.java
 src/org/dartlang/vm/service/consumer/ProcessMemoryUsageConsumer.java
 src/org/dartlang/vm/service/consumer/ProtocolListConsumer.java
+src/org/dartlang/vm/service/consumer/QueuedMicrotasksConsumer.java
 src/org/dartlang/vm/service/consumer/ReloadSourcesConsumer.java
 src/org/dartlang/vm/service/consumer/RemoveBreakpointConsumer.java
 src/org/dartlang/vm/service/consumer/RequestHeapSnapshotConsumer.java
@@ -105,6 +106,7 @@ src/org/dartlang/vm/service/element/LogRecord.java
 src/org/dartlang/vm/service/element/MapAssociation.java
 src/org/dartlang/vm/service/element/MemoryUsage.java
 src/org/dartlang/vm/service/element/Message.java
+src/org/dartlang/vm/service/element/Microtask.java
 src/org/dartlang/vm/service/element/NativeFunction.java
 src/org/dartlang/vm/service/element/Null.java
 src/org/dartlang/vm/service/element/NullRef.java
@@ -119,6 +121,7 @@ src/org/dartlang/vm/service/element/ProcessMemoryUsage.java
 src/org/dartlang/vm/service/element/ProfileFunction.java
 src/org/dartlang/vm/service/element/Protocol.java
 src/org/dartlang/vm/service/element/ProtocolList.java
+src/org/dartlang/vm/service/element/QueuedMicrotasks.java
 src/org/dartlang/vm/service/element/ReloadReport.java
 src/org/dartlang/vm/service/element/Response.java
 src/org/dartlang/vm/service/element/RetainingObject.java

pkg/vm_service/java/version.properties

@@ -1 +1 @@
-version=4.18
+version=4.19

pkg/vm_service/lib/src/vm_service.dart

@@ -27,7 +27,7 @@ export 'snapshot_graph.dart'
         HeapSnapshotObjectNoData,
         HeapSnapshotObjectNullData;
 
-const String vmServiceVersion = '4.18.0';
+const String vmServiceVersion = '4.19.0';
 
 /// @optional
 const String optional = 'optional';
@@ -151,6 +151,7 @@ final _typeFactories = <String, Function>{
   'MapAssociation': MapAssociation.parse,
   'MemoryUsage': MemoryUsage.parse,
   'Message': Message.parse,
+  'Microtask': Microtask.parse,
   'NativeFunction': NativeFunction.parse,
   '@Null': NullValRef.parse,
   'Null': NullVal.parse,
@@ -165,6 +166,7 @@ final _typeFactories = <String, Function>{
   'Protocol': Protocol.parse,
   'ProcessMemoryUsage': ProcessMemoryUsage.parse,
   'ProcessMemoryItem': ProcessMemoryItem.parse,
+  'QueuedMicrotasks': QueuedMicrotasks.parse,
   'ReloadReport': ReloadReport.parse,
   'RetainingObject': RetainingObject.parse,
   'RetainingPath': RetainingPath.parse,
@@ -226,6 +228,7 @@ final _methodReturnTypes = <String, List<String>>{
   'getPorts': const ['PortList'],
   'getRetainingPath': const ['RetainingPath'],
   'getProcessMemoryUsage': const ['ProcessMemoryUsage'],
+  'getQueuedMicrotasks': const ['QueuedMicrotasks'],
   'getStack': const ['Stack'],
   'getSupportedProtocols': const ['ProtocolList'],
   'getSourceReport': const ['SourceReport'],
@@ -1255,6 +1258,28 @@ class VmService {
   Future<ProcessMemoryUsage> getProcessMemoryUsage() =>
       _call('getProcessMemoryUsage');
 
+  /// The `getQueuedMicrotasks` RPC returns a snapshot containing information
+  /// about the microtasks that were queued in the specified isolate when the
+  /// snapshot was taken.
+  ///
+  /// If the VM was not started with the flag `--profile-microtasks`, this RPC
+  /// will return [RPCError] 100 "Feature is disabled".
+  ///
+  /// If an exception has gone unhandled in the specified isolate, this RPC will
+  /// return [RPCError] 115 "Cannot get queued microtasks".
+  ///
+  /// If custom `dart:async` `Zone`s are used to redirect microtasks to be
+  /// queued elsewhere than the root `dart:async` `Zone`'s microtask queue,
+  /// information about those redirected microtasks will not be returned by this
+  /// function.
+  ///
+  /// If `isolateId` refers to an isolate that has exited, then the `Collected`
+  /// [Sentinel] will be returned.
+  ///
+  /// See [QueuedMicrotasks].
+  Future<QueuedMicrotasks> getQueuedMicrotasks(String isolateId) =>
+      _call('getQueuedMicrotasks', {'isolateId': isolateId});
+
   /// The `getStack` RPC is used to retrieve the current execution stack and
   /// message queue for an isolate. The isolate does not need to be paused.
   ///
@@ -2150,6 +2175,11 @@ enum RPCErrorKind {
       message:
           'Invalid timeline request for the current timeline configuration'),
 
+  /// Information about the microtasks queued in the specified isolate cannot be
+  /// retrieved.
+  kCannotGetQueuedMicrotasks(
+      code: 115, message: 'Cannot get queued microtasks'),
+
   /// The custom stream does not exist.
   kCustomStreamDoesNotExist(code: 130, message: 'Custom stream does not exist'),
 
@@ -6654,6 +6684,51 @@ class Message extends Response {
       'size: $size]';
 }
 
+/// A `Microtask` represents a Dart microtask.
+///
+/// See [QueuedMicrotasks].
+class Microtask extends Response {
+  static Microtask? parse(Map<String, dynamic>? json) =>
+      json == null ? null : Microtask._fromJson(json);
+
+  /// The numeric ID for this microtask.
+  ///
+  /// This ID uniquely identifies a microtask within an isolate.
+  int? id;
+
+  /// A stack trace that was collected when this microtask was enqueued.
+  String? stackTrace;
+
+  Microtask({
+    this.id,
+    this.stackTrace,
+  });
+
+  Microtask._fromJson(Map<String, dynamic> json) : super._fromJson(json) {
+    id = json['id'] ?? -1;
+    stackTrace = json['stackTrace'] ?? '';
+  }
+
+  @override
+  String get type => 'Microtask';
+
+  @override
+  Map<String, dynamic> toJson() => <String, Object?>{
+        'type': type,
+        'id': id ?? -1,
+        'stackTrace': stackTrace ?? '',
+      };
+
+  @override
+  int get hashCode => id.hashCode;
+
+  @override
+  bool operator ==(Object other) => other is Microtask && id == other.id;
+
+  @override
+  String toString() => '[Microtask id: $id, stackTrace: $stackTrace]';
+}
+
 /// A `NativeFunction` object is used to represent native functions in profiler
 /// samples. See [CpuSamples];
 class NativeFunction {
@@ -7302,6 +7377,51 @@ class ProcessMemoryItem {
       'name: $name, description: $description, size: $size, children: $children]';
 }
 
+/// A `QueuedMicrotasks` object is a snapshot containing information about the
+/// microtasks that were queued in a certain isolate at a certain time.
+///
+/// See [VmService.getQueuedMicrotasks] and [Microtask].
+class QueuedMicrotasks extends Response {
+  static QueuedMicrotasks? parse(Map<String, dynamic>? json) =>
+      json == null ? null : QueuedMicrotasks._fromJson(json);
+
+  /// The time at which this snapshot of the microtask queue was taken,
+  /// represented as microseconds since the "Unix epoch".
+  int? timestamp;
+
+  /// The microtasks that were in the queue when this snapshot was taken. The
+  /// microtask at the front of the queue (i.e. the one that will run earliest)
+  /// is the one at index 0 of this list.
+  List<Microtask>? microtasks;
+
+  QueuedMicrotasks({
+    this.timestamp,
+    this.microtasks,
+  });
+
+  QueuedMicrotasks._fromJson(Map<String, dynamic> json)
+      : super._fromJson(json) {
+    timestamp = json['timestamp'] ?? -1;
+    microtasks = List<Microtask>.from(
+        createServiceObject(json['microtasks'], const ['Microtask']) as List? ??
+            []);
+  }
+
+  @override
+  String get type => 'QueuedMicrotasks';
+
+  @override
+  Map<String, dynamic> toJson() => <String, Object?>{
+        'type': type,
+        'timestamp': timestamp ?? -1,
+        'microtasks': microtasks?.map((f) => f.toJson()).toList(),
+      };
+
+  @override
+  String toString() =>
+      '[QueuedMicrotasks timestamp: $timestamp, microtasks: $microtasks]';
+}
+
 class ReloadReport extends Response {
   static ReloadReport? parse(Map<String, dynamic>? json) =>
       json == null ? null : ReloadReport._fromJson(json);

pkg/vm_service/pubspec.yaml

@@ -1,5 +1,5 @@
 name: vm_service
-version: 15.0.0
+version: 15.0.1-wip
 description: >-
   A library to communicate with a service implementing the Dart VM
   service protocol.

pkg/vm_service/test/get_queued_microtasks_rpc_test.dart

@@ -0,0 +1,49 @@
+// Copyright (c) 2025, 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 'dart:async';
+import 'dart:developer';
+
+import 'package:test/test.dart';
+import 'package:vm_service/vm_service.dart';
+
+import 'common/service_test_common.dart';
+import 'common/test_helper.dart';
+
+const String shortFile = 'get_queued_microtasks_rpc_test.dart';
+const int numberOfMicrotasksToSchedule = 5;
+
+Future<void> testeeMain() async {
+  for (int i = 0; i < numberOfMicrotasksToSchedule; i++) {
+    scheduleMicrotask(() {});
+    debugger();
+    // Give the microtask that we just scheduled an opportunity to run.
+    await Future.delayed(const Duration(milliseconds: 1));
+  }
+}
+
+final tests = <IsolateTest>[
+  (VmService service, IsolateRef isolateRef) async {
+    for (int i = 0; i < numberOfMicrotasksToSchedule; i++) {
+      await hasStoppedAtBreakpoint(service, isolateRef);
+      final result = await service.getQueuedMicrotasks(
+        isolateRef.id!,
+      );
+
+      expect(result.timestamp, isPositive);
+      expect(result.microtasks!.length, 1);
+      expect(result.microtasks!.first.id, i);
+      expect(result.microtasks!.first.stackTrace, contains(shortFile));
+      await service.resume(isolateRef.id!);
+    }
+  },
+];
+
+Future<void> main([args = const <String>[]]) => runIsolateTests(
+      args,
+      tests,
+      shortFile,
+      testeeConcurrent: testeeMain,
+      extraArgs: ['--profile-microtasks'],
+    );

pkg/vm_service/tool/dart/generate_dart_client.dart

@@ -334,6 +334,10 @@ enum RPCErrorKind {
   kInvalidTimelineRequest(code: 114,
       message: 'Invalid timeline request for the current timeline configuration'),
 
+  /// Information about the microtasks queued in the specified isolate cannot be
+  /// retrieved.
+  kCannotGetQueuedMicrotasks(code: 115, message: 'Cannot get queued microtasks'),
+
   /// The custom stream does not exist.
   kCustomStreamDoesNotExist(code: 130, message: 'Custom stream does not exist'),
 

pkg/vm_service_interface/lib/src/vm_service_interface.dart

@@ -17,7 +17,7 @@ import 'service_extension_registry.dart';
 
 export 'service_extension_registry.dart' show ServiceExtensionRegistry;
 
-const String vmServiceVersion = '4.18.0';
+const String vmServiceVersion = '4.19.0';
 
 /// A class representation of the Dart VM Service Protocol.
 abstract interface class VmServiceInterface {
@@ -784,6 +784,27 @@ abstract interface class VmServiceInterface {
   /// addition of any bucket.
   Future<ProcessMemoryUsage> getProcessMemoryUsage();
 
+  /// The `getQueuedMicrotasks` RPC returns a snapshot containing information
+  /// about the microtasks that were queued in the specified isolate when the
+  /// snapshot was taken.
+  ///
+  /// If the VM was not started with the flag `--profile-microtasks`, this RPC
+  /// will return [RPCError] 100 "Feature is disabled".
+  ///
+  /// If an exception has gone unhandled in the specified isolate, this RPC will
+  /// return [RPCError] 115 "Cannot get queued microtasks".
+  ///
+  /// If custom `dart:async` `Zone`s are used to redirect microtasks to be
+  /// queued elsewhere than the root `dart:async` `Zone`'s microtask queue,
+  /// information about those redirected microtasks will not be returned by this
+  /// function.
+  ///
+  /// If `isolateId` refers to an isolate that has exited, then the `Collected`
+  /// [Sentinel] will be returned.
+  ///
+  /// See [QueuedMicrotasks].
+  Future<QueuedMicrotasks> getQueuedMicrotasks(String isolateId);
+
   /// The `getStack` RPC is used to retrieve the current execution stack and
   /// message queue for an isolate. The isolate does not need to be paused.
   ///
@@ -1606,6 +1627,11 @@ class VmServerConnection {
         case 'getProcessMemoryUsage':
           response = await _serviceImplementation.getProcessMemoryUsage();
           break;
+        case 'getQueuedMicrotasks':
+          response = await _serviceImplementation.getQueuedMicrotasks(
+            params!['isolateId'],
+          );
+          break;
         case 'getStack':
           response = await _serviceImplementation.getStack(
             params!['isolateId'],