Version 2.1.0. (#72)
Update the documentation to mention AsyncBenchmarkBase and the future
direction for the behavior of exercise() calling run() once instead of
10 times.
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3fe742a..c6d581f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,4 +1,6 @@
-## 2.0.1-dev
+## 2.1.0
+
+- Add AsyncBenchmarkBase.
## 2.0.0
diff --git a/README.md b/README.md
index ac20162..1274827 100644
--- a/README.md
+++ b/README.md
@@ -1,14 +1,25 @@
# Dart Benchmark Harness
-The Dart project benchmark harness is the recommended starting point when building a benchmark for Dart.
+The Dart project benchmark harness is the recommended starting point when
+building a benchmark for Dart.
## Interpreting Results
-By default, the reported runtime is not for a single call to `run()`, but for
-the average time it takes to call `run()` __10 times__. The
-benchmark harness executes a 10-call timing loop repeatedly until 2 seconds
-have elapsed; the reported result is the average of the runtimes for each
-loop.
+By default, the reported runtime in `BenchmarkBase` is not for a single call to
+`run()`, but for the average time it takes to call `run()` __10 times__ for
+legacy reasons. The benchmark harness executes a 10-call timing loop repeatedly
+until 2 seconds have elapsed; the reported result is the average of the runtimes
+for each loop. This behavior will change in a future major version.
+
+Benchmarks extending `BenchmarkBase` can opt into the reporting the average time
+to call `run()` once by overriding the `exercise` method:
+
+```dart
+ @override
+ void exercise() => run();
+```
+
+`AsyncBenchmarkBase` already reports the average time to call `run()` __once__.
## Comparing Results
@@ -23,9 +34,9 @@
## Features
-* `BenchmarkBase` class that all new benchmarks should `extend`
-* Two sample benchmarks (DeltaBlue & Richards)
-* Template benchmark that you can copy and paste when building new benchmarks
+* `BenchmarkBase` class that all new benchmarks should `extend`.
+* `AsyncBenchmarkBase` for asynchronous benchmarks.
+* Template benchmark that you can copy and paste when building new benchmarks.
## Getting Started
@@ -48,11 +59,13 @@
import 'package:benchmark_harness/benchmark_harness.dart';
```
-4\. Create a benchmark class which inherits from `BenchmarkBase`
+4\. Create a benchmark class which inherits from `BenchmarkBase` or
+ `AsyncBenchmarkBase`.
## Example
-Create a dart file in the [`benchmark/`](https://dart.dev/tools/pub/package-layout#tests-and-benchmarks)
+Create a dart file in the
+[`benchmark/`](https://dart.dev/tools/pub/package-layout#tests-and-benchmarks)
folder of your package.
```dart
@@ -78,6 +91,10 @@
// Not measured teardown code executed after the benchmark runs.
@override
void teardown() {}
+
+ // To opt into the reporting the time per run() instead of per 10 run() calls.
+ //@override
+ //void exercise() => run();
}
void main() {
@@ -92,9 +109,12 @@
Template(RunTime): 0.1568472448997197 us.
```
-This is the average amount of time it takes to run `run()` 10 times.
+This is the average amount of time it takes to run `run()` 10 times for
+`BenchmarkBase` and once for `AsyncBenchmarkBase`.
> µs is an abbreviation for microseconds.
### Contributions
-This package is carefully curated by the Dart team to exact specifications. Please open an issue with any proposed changes, before submitting a Pull Request.
+This package is carefully curated by the Dart team to exact specifications.
+Please open an issue with any proposed changes, before submitting a Pull
+Request.
diff --git a/example/template.dart b/example/template.dart
index 43db1cd..194e411 100644
--- a/example/template.dart
+++ b/example/template.dart
@@ -1,4 +1,3 @@
-// @dart=2.8
// Copyright (c) 2021, 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.
@@ -25,6 +24,10 @@
// Not measures teardown code executed after the benchark runs.
@override
void teardown() {}
+
+ // To opt into the reporting the time per run() instead of per 10 run() calls.
+ //@override
+ //void exercise() => run();
}
void main() {
diff --git a/pubspec.yaml b/pubspec.yaml
index cd6fecb..4c436c6 100644
--- a/pubspec.yaml
+++ b/pubspec.yaml
@@ -1,5 +1,5 @@
name: benchmark_harness
-version: 2.0.1-dev
+version: 2.1.0
description: The official Dart project benchmark harness.
repository: https://github.com/dart-lang/benchmark_harness
