[ VM / Service ] Add optional 'limit' parameter to getStack RPC

Allows for clients to request the top N frames of the current stack.

Fixes dart-lang/sdk#43826

Change-Id: Ia8d38e6317373024382a5e857faff73c89a0d2c0
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/169980
Reviewed-by: Ryan Macnak <rmacnak@google.com>
Reviewed-by: Gary Roumanis <grouma@google.com>
Commit-Queue: Ben Konyi <bkonyi@google.com>

Author: bkonyi

pkg/vm_service/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 5.5.0
+- Update to version `3.42.0` of the spec.
+- Added optional `limit` parameter to `getStack` RPC.
+
 ## 5.4.0
 - Update to version `3.41.0` of the spec.
 - Added `PortList` class.

pkg/vm_service/example/vm_service_assert.dart

@@ -1105,6 +1105,7 @@ vms.Stack assertStack(vms.Stack obj) {
   assertString(obj.type);
   assertListOfFrame(obj.frames);
   assertListOfMessage(obj.messages);
+  assertBool(obj.truncated);
   return obj;
 }
 

pkg/vm_service/java/version.properties

@@ -1 +1 @@
-version=3.41
+version=3.42

pkg/vm_service/lib/src/vm_service.dart

@@ -28,7 +28,7 @@ export 'snapshot_graph.dart'
         HeapSnapshotObjectNoData,
         HeapSnapshotObjectNullData;
 
-const String vmServiceVersion = '3.41.0';
+const String vmServiceVersion = '3.42.0';
 
 /// @optional
 const String optional = 'optional';
@@ -733,14 +733,20 @@ abstract class VmServiceInterface {
   /// 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].
   ///
   /// This method will throw a [SentinelException] in the case a [Sentinel] is
   /// returned.
-  Future<Stack> getStack(String isolateId);
+  Future<Stack> getStack(String isolateId, {int limit});
 
   /// The `getSupportedProtocols` RPC is used to determine which protocols are
   /// supported by the current server.
@@ -1344,6 +1350,7 @@ class VmServerConnection {
         case 'getStack':
           response = await _serviceImplementation.getStack(
             params['isolateId'],
+            limit: params['limit'],
           );
           break;
         case 'getSupportedProtocols':
@@ -1798,8 +1805,10 @@ class VmService implements VmServiceInterface {
       _call('getProcessMemoryUsage');
 
   @override
-  Future<Stack> getStack(String isolateId) =>
-      _call('getStack', {'isolateId': isolateId});
+  Future<Stack> getStack(String isolateId, {int limit}) => _call('getStack', {
+        'isolateId': isolateId,
+        if (limit != null) 'limit': limit,
+      });
 
   @override
   Future<ProtocolList> getSupportedProtocols() =>
@@ -6664,23 +6673,40 @@ class SourceReportRange {
       'compiled: ${compiled}]';
 }
 
+/// The `Stack` class represents the various components of a Dart stack trace
+/// for a given isolate.
+///
+/// See [getStack].
 class Stack extends Response {
   static Stack parse(Map<String, dynamic> json) =>
       json == null ? null : Stack._fromJson(json);
 
+  /// 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).
   List<Frame> frames;
 
+  /// A list of frames representing the asynchronous path. Comparable to
+  /// `awaiterFrames`, if provided, although some frames may be different.
   @optional
   List<Frame> asyncCausalFrames;
 
+  /// A list of frames representing the asynchronous path. Comparable to
+  /// `asyncCausalFrames`, if provided, although some frames may be different.
   @optional
   List<Frame> awaiterFrames;
 
+  /// A list of messages in the isolate's message queue.
   List<Message> messages;
 
+  /// Specifies whether or not this stack is complete or has been artificially
+  /// truncated.
+  bool truncated;
+
   Stack({
     @required this.frames,
     @required this.messages,
+    @required this.truncated,
     this.asyncCausalFrames,
     this.awaiterFrames,
   });
@@ -6698,6 +6724,7 @@ class Stack extends Response {
             createServiceObject(json['awaiterFrames'], const ['Frame']));
     messages = List<Message>.from(
         createServiceObject(json['messages'], const ['Message']) ?? []);
+    truncated = json['truncated'];
   }
 
   @override
@@ -6707,6 +6734,7 @@ class Stack extends Response {
     json.addAll({
       'frames': frames.map((f) => f.toJson()).toList(),
       'messages': messages.map((f) => f.toJson()).toList(),
+      'truncated': truncated,
     });
     _setIfNotNull(json, 'asyncCausalFrames',
         asyncCausalFrames?.map((f) => f?.toJson())?.toList());
@@ -6715,8 +6743,9 @@ class Stack extends Response {
     return json;
   }
 
-  String toString() =>
-      '[Stack type: ${type}, frames: ${frames}, messages: ${messages}]';
+  String toString() => '[Stack ' //
+      'type: ${type}, frames: ${frames}, messages: ${messages}, ' //
+      'truncated: ${truncated}]';
 }
 
 /// The `Success` type is used to indicate that an operation completed

pkg/vm_service/pubspec.yaml

@@ -2,7 +2,7 @@ name: vm_service
 description: >-
   A library to communicate with a service implementing the Dart VM
   service protocol.
-version: 5.4.0
+version: 5.5.0
 
 homepage: https://github.com/dart-lang/sdk/tree/master/pkg/vm_service
 

runtime/observatory/lib/src/service/object.dart

@@ -1917,8 +1917,10 @@ class Isolate extends ServiceObjectOwner implements M.Isolate {
     return invokeRpc('setExceptionPauseMode', {'mode': mode});
   }
 
-  Future<ServiceMap> getStack() {
-    return invokeRpc('getStack', {}).then((response) => response as ServiceMap);
+  Future<ServiceMap> getStack({int? limit}) {
+    return invokeRpc('getStack', {
+      if (limit != null) 'limit': limit,
+    }).then((response) => response as ServiceMap);
   }
 
   Future<ObjectStore> getObjectStore() {

runtime/observatory/tests/service/get_stack_limit_rpc_test.dart

@@ -0,0 +1,102 @@
+// 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 'dart:async';
+import 'dart:developer';
+
+import 'package:observatory/models.dart' as M;
+import 'package:observatory/service_io.dart';
+import 'package:test/test.dart';
+import 'service_test_common.dart';
+import 'test_helper.dart';
+
+bar(int depth) {
+  if (depth == 21) {
+    debugger();
+    return;
+  }
+  foo(depth + 1);
+}
+
+foo(int depth) {
+  bar(depth + 1);
+}
+
+testMain() {
+  foo(0);
+}
+
+verifyStack(List frames, int numFrames) {
+  for (int i = 0; i < frames.length && i < numFrames; ++i) {
+    final frame = frames[i];
+    if (i < 22) {
+      expect(frame.function!.qualifiedName, (i % 2) == 0 ? 'bar' : 'foo');
+    } else if (i == 22) {
+      expect(frame.function!.qualifiedName, 'testMain');
+      break;
+    }
+  }
+}
+
+var tests = <IsolateTest>[
+  (Isolate isolate) async {
+    await hasStoppedAtBreakpoint(isolate);
+    // Sanity check.
+    expect(isolate.pauseEvent is M.PauseBreakpointEvent, isTrue);
+  },
+
+// Get stack
+  (Isolate isolate) async {
+    var stack = await isolate.getStack();
+    // Sanity check.
+    var frames = stack['frames'];
+    var asyncFrames = stack['asyncCausalFrames'];
+    var awaiterFrames = stack['awaiterFrames'];
+    expect(frames.length, greaterThanOrEqualTo(20));
+    expect(asyncFrames.length, greaterThan(frames.length));
+    expect(awaiterFrames.length, greaterThan(frames.length));
+    expect(stack['truncated'], false);
+
+    verifyStack(frames, frames.length);
+
+    final fullStackLength = frames.length;
+
+    // Try a limit > actual stack depth and expect to get the full stack with
+    // truncated async stacks.
+    stack = await isolate.getStack(limit: fullStackLength + 1);
+    frames = stack['frames'];
+    asyncFrames = stack['asyncCausalFrames'];
+    awaiterFrames = stack['awaiterFrames'];
+
+    expect(frames.length, fullStackLength);
+    expect(asyncFrames.length, fullStackLength + 1);
+    expect(asyncFrames.length, fullStackLength + 1);
+    expect(stack['truncated'], true);
+    verifyStack(frames, fullStackLength);
+
+    // Try a limit < actual stack depth and expect to get a stack of depth
+    // 'limit'.
+    stack = await isolate.getStack(limit: 10);
+    frames = stack['frames'];
+    asyncFrames = stack['asyncCausalFrames'];
+    awaiterFrames = stack['awaiterFrames'];
+
+    expect(frames.length, 10);
+    expect(asyncFrames.length, 10);
+    expect(awaiterFrames.length, 10);
+    expect(stack['truncated'], true);
+    verifyStack(frames, 10);
+  },
+// Invalid limit
+  (Isolate isolate) async {
+    try {
+      await isolate.getStack(limit: -1);
+      fail('Invalid parameter of -1 successful');
+    } on ServerRpcException {
+      // Expected.
+    }
+  }
+];
+
+main(args) => runIsolateTests(args, tests, testeeConcurrent: testMain);

runtime/observatory/tests/service/get_version_rpc_test.dart

@@ -12,7 +12,7 @@ var tests = <VMTest>[
     final result = await vm.invokeRpcNoUpgrade('getVersion', {});
     expect(result['type'], 'Version');
     expect(result['major'], 3);
-    expect(result['minor'], 41);
+    expect(result['minor'], 42);
     expect(result['_privateMajor'], 0);
     expect(result['_privateMinor'], 0);
   },

runtime/observatory_2/lib/src/service/object.dart

@@ -1927,8 +1927,10 @@ class Isolate extends ServiceObjectOwner implements M.Isolate {
     return invokeRpc('setExceptionPauseMode', {'mode': mode});
   }
 
-  Future<ServiceMap> getStack() {
-    return invokeRpc('getStack', {}).then((response) => response as ServiceMap);
+  Future<ServiceMap> getStack({int limit}) {
+    return invokeRpc('getStack', {
+      if (limit != null) 'limit': limit,
+    }).then((response) => response as ServiceMap);
   }
 
   Future<ObjectStore> getObjectStore() {

runtime/observatory_2/tests/service_2/get_stack_limit_rpc_test.dart

@@ -0,0 +1,102 @@
+// 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 'dart:async';
+import 'dart:developer';
+
+import 'package:observatory_2/models.dart' as M;
+import 'package:observatory_2/service_io.dart';
+import 'package:test/test.dart';
+import 'service_test_common.dart';
+import 'test_helper.dart';
+
+bar(int depth) {
+  if (depth == 21) {
+    debugger();
+    return;
+  }
+  foo(depth + 1);
+}
+
+foo(int depth) {
+  bar(depth + 1);
+}
+
+testMain() {
+  foo(0);
+}
+
+verifyStack(List frames, int numFrames) {
+  for (int i = 0; i < frames.length && i < numFrames; ++i) {
+    final frame = frames[i];
+    if (i < 22) {
+      expect(frame.function.qualifiedName, (i % 2) == 0 ? 'bar' : 'foo');
+    } else if (i == 22) {
+      expect(frame.function.qualifiedName, 'testMain');
+      break;
+    }
+  }
+}
+
+var tests = <IsolateTest>[
+  (Isolate isolate) async {
+    await hasStoppedAtBreakpoint(isolate);
+    // Sanity check.
+    expect(isolate.pauseEvent is M.PauseBreakpointEvent, isTrue);
+  },
+
+// Get stack
+  (Isolate isolate) async {
+    var stack = await isolate.getStack();
+    // Sanity check.
+    var frames = stack['frames'];
+    var asyncFrames = stack['asyncCausalFrames'];
+    var awaiterFrames = stack['awaiterFrames'];
+    expect(frames.length, greaterThanOrEqualTo(20));
+    expect(asyncFrames.length, greaterThan(frames.length));
+    expect(awaiterFrames.length, greaterThan(frames.length));
+    expect(stack['truncated'], false);
+
+    verifyStack(frames, frames.length);
+
+    final fullStackLength = frames.length;
+
+    // Try a limit > actual stack depth and expect to get the full stack with
+    // truncated async stacks.
+    stack = await isolate.getStack(limit: fullStackLength + 1);
+    frames = stack['frames'];
+    asyncFrames = stack['asyncCausalFrames'];
+    awaiterFrames = stack['awaiterFrames'];
+
+    expect(frames.length, fullStackLength);
+    expect(asyncFrames.length, fullStackLength + 1);
+    expect(asyncFrames.length, fullStackLength + 1);
+    expect(stack['truncated'], true);
+    verifyStack(frames, fullStackLength);
+
+    // Try a limit < actual stack depth and expect to get a stack of depth
+    // 'limit'.
+    stack = await isolate.getStack(limit: 10);
+    frames = stack['frames'];
+    asyncFrames = stack['asyncCausalFrames'];
+    awaiterFrames = stack['awaiterFrames'];
+
+    expect(frames.length, 10);
+    expect(asyncFrames.length, 10);
+    expect(awaiterFrames.length, 10);
+    expect(stack['truncated'], true);
+    verifyStack(frames, 10);
+  },
+// Invalid limit
+  (Isolate isolate) async {
+    try {
+      await isolate.getStack(limit: -1);
+      fail('Invalid parameter of -1 successful');
+    } on ServerRpcException {
+      // Expected.
+    }
+  }
+];
+
+main(args) => runIsolateTests(args, tests, testeeConcurrent: testMain);