Minor clarifications.

Add some comments, use `where` clauses, and rename some things.

Author: nnethercote

collector/benchlib/src/benchmark.rs

@@ -5,12 +5,16 @@ use crate::measure::benchmark_function;
 use crate::process::raise_process_priority;
 use std::collections::HashMap;
 
-/// Create a new benchmark group. Use the closure argument to define individual benchmarks.
-pub fn run_benchmark_group<F: FnOnce(&mut BenchmarkGroup)>(define_func: F) {
+/// Create and run a new benchmark group. Use the closure argument to register
+/// the individual benchmarks.
+pub fn run_benchmark_group<F>(register: F)
+where
+    F: FnOnce(&mut BenchmarkGroup),
+{
     env_logger::init();
 
     let mut group = BenchmarkGroup::new();
-    define_func(&mut group);
+    register(&mut group);
     group.run().expect("Benchmark group execution has failed");
 }
 
@@ -28,16 +32,21 @@ impl BenchmarkGroup {
     }
 
     /// Registers a single benchmark.
-    /// `constructor` should return a closure that will be benchmarked.
-    pub fn register<F: Fn() -> Bench + Clone + 'static, R, Bench: FnOnce() -> R + 'static>(
-        &mut self,
-        name: &'static str,
-        constructor: F,
-    ) {
+    ///
+    /// `constructor` returns a closure that will be benchmarked. This means
+    /// `constructor` can do initialization steps outside of the code that is
+    /// measured. `constructor` may be called multiple times (e.g. once for a
+    /// run with performance counters and once for a run without), but the
+    /// closure it produces each time will only be called once.
+    pub fn register_benchmark<Ctor, Bench, R>(&mut self, name: &'static str, constructor: Ctor)
+    where
+        Ctor: Fn() -> Bench + Clone + 'static,
+        Bench: FnOnce() -> R + 'static,
+    {
         // We want to type-erase the target `func` by wrapping it in a Box.
         let benchmark_fn = Box::new(move || benchmark_function(constructor.clone()));
         if self.benchmarks.insert(name, benchmark_fn).is_some() {
-            panic!("Benchmark {} was registered twice", name);
+            panic!("Benchmark '{}' was registered twice", name);
         }
     }
 
@@ -108,7 +117,7 @@ impl BenchmarkGroup {
 macro_rules! define_benchmark {
     ($group:expr, $name:ident, $fun:expr) => {
         let func = move || $fun;
-        $group.register(stringify!($name), func);
+        $group.register_benchmark(stringify!($name), func);
     };
 }