Version 2.3.0 (#102)

* Version 2.3.0

 - Update SDK requirement to Dart 3.2.

 - Add a ScoreEmitterV2 interface, that the ScoreEmitter interface
   will be changed to in the next major release, a breaking change.

 - Add `PerfBenchmarkBase` class which runs the 'perf stat' command from
   linux-tools on a benchmark and reports metrics from the hardware
   performance counters and the benchmark iteration count.

The breaking change to ScoreEmitter in 2.2.3 is reverted, and version
2.2.3 is retracted from pub.

* Update version number

* Improve documentation

Author: whesse

CHANGELOG.md

@@ -1,6 +1,9 @@
-## 2.2.3
+## 2.3.0
 
 - Require Dart 3.2.
+- Add ScoreEmitterV2 interface, documented with the intention to change
+ScoreEmitter interface to match it in the next major release,
+ a breaking change.
 - Add `PerfBenchmarkBase` class which runs the 'perf stat' command from
 linux-tools on a benchmark and reports metrics from the hardware
 performance counters and the iteration count, as well as the run time

lib/src/async_benchmark_base.dart

@@ -64,6 +64,6 @@ class AsyncBenchmarkBase {
 
   /// Run the benchmark and report results on the [emitter].
   Future<void> report() async {
-    emitter.emit(name, await measure(), unit: 'us.');
+    emitter.emit(name, await measure());
   }
 }

lib/src/benchmark_base.dart

@@ -58,7 +58,7 @@ class BenchmarkBase {
   }
 
   void report() {
-    emitter.emit(name, measure(), unit: 'us.');
+    emitter.emit(name, measure());
   }
 }
 

lib/src/perf_benchmark_base.dart

@@ -18,7 +18,10 @@ class PerfBenchmarkBase extends BenchmarkBase {
   late final Process perfProcess;
   late final List<String> perfProcessArgs;
 
-  PerfBenchmarkBase(super.name, {super.emitter = const PrintEmitter()});
+  PerfBenchmarkBase(super.name,
+      {ScoreEmitterV2 super.emitter = const PrintEmitterV2()});
+
+  ScoreEmitterV2 get _emitterV2 => emitter as ScoreEmitterV2;
 
   Future<void> _createFifos() async {
     perfControlFifo = '${fifoDir.path}/perf_control_fifo';
@@ -81,11 +84,11 @@ class PerfBenchmarkBase extends BenchmarkBase {
             String event && ('cycles' || 'page-faults'),
             ...
           ]) {
-        emitter.emit(name, double.parse(counter) / totalIterations,
+        _emitterV2.emit(name, double.parse(counter) / totalIterations,
             metric: metrics[event]!);
       }
     }
-    emitter.emit('$name.totalIterations', totalIterations.toDouble(),
+    _emitterV2.emit('$name.totalIterations', totalIterations.toDouble(),
         metric: 'Count');
   }
 
@@ -118,7 +121,7 @@ class PerfBenchmarkBase extends BenchmarkBase {
   }
 
   Future<void> reportPerf() async {
-    emitter.emit(name, await measurePerf(), unit: 'us.');
+    _emitterV2.emit(name, await measurePerf(), unit: 'us.');
   }
 
   void _waitForAck() {

lib/src/score_emitter.dart

@@ -3,13 +3,33 @@
 // BSD-style license that can be found in the LICENSE file.
 
 abstract class ScoreEmitter {
-  void emit(String testName, double value,
-      {String metric = 'RunTime', String unit});
+  void emit(String testName, double value);
 }
 
 class PrintEmitter implements ScoreEmitter {
   const PrintEmitter();
 
+  @override
+  void emit(String testName, double value) {
+    print('$testName(RunTime): $value us.');
+  }
+}
+
+/// New interface for [ScoreEmitter]. [ScoreEmitter] will be changed to
+/// this interface in the next major version release, and this class will
+/// be deprecated and removed.  That release will be a breaking change.
+abstract class ScoreEmitterV2 implements ScoreEmitter {
+  @override
+  void emit(String testName, double value,
+      {String metric = 'RunTime', String unit});
+}
+
+/// New implementation of [PrintEmitter] implementing the [ScoreEmitterV2]
+/// interface.  [PrintEmitter] will be changed to this implementation in the
+/// next major version release.
+class PrintEmitterV2 implements ScoreEmitterV2 {
+  const PrintEmitterV2();
+
   @override
   void emit(String testName, double value,
       {String metric = 'RunTime', String unit = ''}) {

pubspec.yaml

@@ -1,5 +1,5 @@
 name: benchmark_harness
-version: 2.2.3
+version: 2.3.0
 description: The official Dart project benchmark harness.
 repository: https://github.com/dart-lang/benchmark_harness
 

test/result_emitter_test.dart

@@ -13,8 +13,7 @@ class MockResultEmitter extends ScoreEmitter {
   int emitCount = 0;
 
   @override
-  void emit(String name, double value,
-      {String metric = 'RunTime', String unit = ''}) {
+  void emit(String name, double value) {
     emitCount++;
   }
 }