Macro iai_callgrind::binary_benchmark_group

macro_rules! binary_benchmark_group {
    (
        $( config = $config:expr ; $(;)* )?
        benchmark = |$cmd:expr, $group:ident: &mut BinaryBenchmarkGroup| $body:expr
    ) => { ... };
    (
        $( config = $config:expr ; $(;)* )?
        benchmark = |$group:ident: &mut BinaryBenchmarkGroup| $body:expr
    ) => { ... };
    (
        name = $name:ident;
        $( config = $config:expr ; $(;)* )?
        benchmark =
    ) => { ... };
    (
        name = $name:ident; $(;)*
        $(before = $before:ident $(,bench = $bench_before:literal)? ; $(;)*)?
        $(after = $after:ident $(,bench = $bench_after:literal)? ; $(;)*)?
        $(setup = $setup:ident $(,bench = $bench_setup:literal)? ; $(;)*)?
        $(teardown = $teardown:ident $(,bench = $bench_teardown:literal)? ; $(;)*)?
        $( config = $config:expr ; $(;)* )?
        benchmark = |$cmd:expr, $group:ident: &mut BinaryBenchmarkGroup| $body:expr
    ) => { ... };
    (
        name = $name:ident; $(;)*
        $(before = $before:ident $(,bench = $bench_before:literal)? ; $(;)*)?
        $(after = $after:ident $(,bench = $bench_after:literal)? ; $(;)*)?
        $(setup = $setup:ident $(,bench = $bench_setup:literal)? ; $(;)*)?
        $(teardown = $teardown:ident $(,bench = $bench_teardown:literal)? ; $(;)*)?
        $( config = $config:expr ; $(;)* )?
        benchmark = |$group:ident: &mut BinaryBenchmarkGroup| $body:expr
    ) => { ... };
}

Macro used to define a group of binary benchmarks

A small introductory example which shows the basic setup:

use iai_callgrind::{binary_benchmark_group, BinaryBenchmarkGroup};

binary_benchmark_group!(
    name = my_group;
    benchmark = |group: &mut BinaryBenchmarkGroup| {
        // code to setup and configure the benchmarks in a group
    }
);

iai_callgrind::main!(binary_benchmark_groups = my_group);

To be benchmarked a binary_benchmark_group has to be added to the main! macro by adding its name to the binary_benchmark_groups argument of the main! macro. See there for further details about the crate::main macro.

This macro accepts two forms which slightly differ in the benchmark argument. In general, each group shares the same before, after, setup and teardown functions, crate::Fixtures and crate::BinaryBenchmarkConfig.

The following top-level arguments are accepted:

binary_benchmark_group!(
    name = my_group;
    before = run_before;
    after = run_after;
    setup = run_setup;
    teardown = run_teardown;
    config = BinaryBenchmarkConfig::default();
    benchmark = |"my-exe", group: &mut BinaryBenchmarkGroup| {
        // code to setup and configure the benchmarks in a group
    }
);

• name (mandatory): A unique name used to identify the group for the main! macro
• before (optional): A function which is run before all benchmarks
• after (optional): A function which is run after all benchmarks
• setup (optional): A function which is run before any benchmarks
• teardown (optional): A function which is run before any benchmarks
• config (optional): A crate::BinaryBenchmarkConfig

The before, after, setup and teardown arguments accept an additional argument bench = bool

before = run_before, bench = true;

which enables benchmarking of the respective function if wished so. Note that setup and teardown functions are benchmarked only once the first time they are invoked, much like the before and after functions. However, both functions are run as usual before or after any benchmark.

Only the benchmark argument differs. In the first form

benchmark = |"my-exe", group: &mut BinaryBenchmarkGroup| {
    group.bench(Run::with_arg(Arg::new("some id", &["--foo=bar"])))
}

it accepts a command which is the default for all crate::Run of the same benchmark group. This command supports auto-discovery of a crate’s binary. For example if a crate’s binary is named my-exe then it is sufficient to pass "my-exe" to the benchmark argument as shown above.

In the second form:

benchmark = |group: &mut BinaryBenchmarkGroup| {
    // Usually, you should use `env!("CARGO_BIN_EXE_my-exe")` instead of an absolute path to a
    // crate's binary
    group.bench(Run::with_cmd(
        "/path/to/my-exe",
        Arg::new("some id", &["--foo=bar"]),
    ))
}

the command can be left out and each crate::Run of a benchmark group has to define a cmd by itself. Note that crate::Run does not support auto-discovery of a crate’s binary.

If you feel uncomfortable working within the macro you can simply move the code to setup the group’s benchmarks into a separate function like so

use iai_callgrind::{binary_benchmark_group, BinaryBenchmarkGroup, Run, Arg};

fn setup_my_group(group: &mut BinaryBenchmarkGroup) {
    group.bench(Run::with_arg(Arg::new("some id", &["--foo=bar"])));
}

binary_benchmark_group!(
    name = my_group;
    benchmark = |"my-exe", group: &mut BinaryBenchmarkGroup| setup_my_group(group)
);