run method

Future<BenchmarkResult> run({ required String testName, required Future<void> task(int iteration), int iterations = 20, int warmupIterations = 3, void onProgress(int completed, int total)?, })

运行单项基准测试 / Runs a single benchmark.

warmupIterations 次预热不计入统计，用于消除 JIT 与连接建立的噪声 / warmupIterations runs are excluded from the statistics to absorb JIT and connection setup noise. 任务抛出的异常会被计为 BenchmarkResult.failures 而不是中断整轮测试 / Exceptions thrown by task are counted in BenchmarkResult.failures instead of aborting the run.

Implementation

Future<BenchmarkResult> run({
  required String testName,
  required Future<void> Function(int iteration) task,
  int iterations = 20,
  int warmupIterations = 3,
  void Function(int completed, int total)? onProgress,
}) async {
  final totalIterations = math.max(1, iterations);

  for (var i = 0; i < math.max(0, warmupIterations); i++) {
    try {
      await task(i);
    } catch (_) {
      // Warm-up failures are intentionally ignored.
    }
  }

  final samples = <int>[];
  var failures = 0;
  final suiteWatch = Stopwatch()..start();

  for (var i = 0; i < totalIterations; i++) {
    final stopwatch = Stopwatch()..start();
    try {
      await task(i);
      stopwatch.stop();
      samples.add(stopwatch.elapsedMicroseconds);
    } catch (_) {
      failures += 1;
    }
    onProgress?.call(i + 1, totalIterations);
  }

  suiteWatch.stop();
  return BenchmarkResult.fromSamples(
    testName: testName,
    samples: samples,
    totalDuration: suiteWatch.elapsed,
    failures: failures,
    timestamp: DateTime.now(),
  );
}