Struct BinaryBenchmark

pub struct BinaryBenchmark {
    pub id: BenchmarkId,
    pub config: Option<InternalBinaryBenchmarkConfig>,
    pub benches: Vec<Bench>,
    pub setup: Option<fn()>,
    pub teardown: Option<fn()>,
}

Available on crate feature default only.

low level api only: Mirror the crate::binary_benchmark attribute

A BinaryBenchmark can be created in two ways. Either with BinaryBenchmark::new. Or via the crate::binary_benchmark_attribute macro used with a function annotated with the crate::binary_benchmark attribute. So, you can start with the high-level api using the attribute and then go on in the low-level api.

Examples

For examples using BinaryBenchmark::new, see there. Here’s an example using the crate::binary_benchmark_attribute

use iai_callgrind::{
    binary_benchmark, binary_benchmark_group, binary_benchmark_attribute, Bench
};

#[binary_benchmark]
#[bench::foo("foo")]
fn bench_binary(arg: &str) -> iai_callgrind::Command {
    iai_callgrind::Command::new(env!("CARGO_BIN_EXE_my-foo"))
        .arg(arg)
        .build()
}

binary_benchmark_group!(
    name = my_group;
    benchmarks = |group: &mut BinaryBenchmarkGroup| {
        let mut binary_benchmark = binary_benchmark_attribute!(bench_binary);

        // Continue and add another `Bench` to the `BinaryBenchmark`
        binary_benchmark.bench(Bench::new("bar")
            .command(iai_callgrind::Command::new(env!("CARGO_BIN_EXE_my-foo"))
                .arg("bar")
            )
        );

        // Finally, add the `BinaryBenchmark` to the group
        group
            .binary_benchmark(binary_benchmark);
    }
);

Fields

id: BenchmarkId

An id which has to be unique within the same BinaryBenchmarkGroup

In the high-level api this is the name of the function which is annotated by crate::binary_benchmark

config: Option<InternalBinaryBenchmarkConfig>

An optional BinaryBenchmarkConfig which is applied to all Commands within this BinaryBenchmark

benches: Vec<Bench>

All Benches which were added to this BinaryBenchmark

setup: Option<fn()>

The default setup function for all Benches within this BinaryBenchmark. It can be overwritten in a Bench

teardown: Option<fn()>

The default teardown function for all Benches within this BinaryBenchmark. It can be overwritten in a Bench

Implementations

impl BinaryBenchmark

pub fn new<T>(id: T) -> Self

where T: Into<BenchmarkId>,

Create a new BinaryBenchmark

A BinaryBenchmark is the equivalent of the #[binary_benchmark] attribute in the low-level api and needs a BenchmarkId. In the high-level api the id is derived from the function name.

The BenchmarkId is used together with the id of each Bench to create a directory name. This usually limits the combined length of the ids to 255 - 1 but can be less depending on the file system. See BenchmarkId for more details

Scope of uniqueness of the BenchmarkId

The id needs to be unique within the same crate::binary_benchmark_group. It is recommended to use an id which is unique within the whole benchmark file, although doing otherwise does currently not incur any negative consequence.

Examples

use iai_callgrind::{BenchmarkId, BinaryBenchmark};

let binary_benchmark = BinaryBenchmark::new("some_id");
assert_eq!(binary_benchmark.id, BenchmarkId::new("some_id"));

pub fn config<T>(&mut self, config: T) -> &mut Self

where T: Into<InternalBinaryBenchmarkConfig>,

Add a BinaryBenchmarkConfig to this BinaryBenchmark

Examples

use iai_callgrind::{BinaryBenchmark, BinaryBenchmarkConfig};

let binary_benchmark = BinaryBenchmark::new("some_id")
    .config(BinaryBenchmarkConfig::default().env("FOO", "BAR"))
    .clone();

assert_eq!(
    binary_benchmark.config,
    Some(BinaryBenchmarkConfig::default().env("FOO", "BAR").into())
);

pub fn bench<T>(&mut self, bench: T) -> &mut Self

where T: Into<Bench>,

Add a Bench to this BinaryBenchmark

Adding a Bench which doesn’t contain a Command is an error.

Examples

use iai_callgrind::{Bench, BinaryBenchmark, Command};

// Each `Bench` needs at least one `Command`!
let mut bench = Bench::new("some_id");
bench.command(Command::new(env!("CARGO_BIN_EXE_my-echo")));

let binary_benchmark = BinaryBenchmark::new("bench_binary")
    .bench(bench.clone())
    .clone();

assert_eq!(binary_benchmark.benches[0], bench);

pub fn setup(&mut self, setup: fn()) -> &mut Self

Add a setup function to this BinaryBenchmark

This setup function is used in all Benches of this BinaryBenchmark if not overridden by the Bench.

Examples

use iai_callgrind::Bench;
fn my_setup() {
    println!(
        "Place everything in this function you want to be executed before the execution of \
         the Command"
    );
}

let bench = Bench::new("some_id").setup(my_setup).clone();

assert!(bench.setup.is_some())

Overwrite the setup function from this BinaryBenchmark in a Bench

use iai_callgrind::{Bench, BinaryBenchmark};
fn binary_benchmark_setup() {
    println!("setup in BinaryBenchmark")
}

fn bench_setup() {
    println!("setup in Bench")
}

BinaryBenchmark::new("bench_binary")
    .setup(binary_benchmark_setup)
    .bench(Bench::new("some_id").setup(bench_setup));

pub fn teardown(&mut self, teardown: fn()) -> &mut Self

Add a teardown function to this BinaryBenchmark

This teardown function is used in all Benches of this BinaryBenchmark if not overridden by the Bench.

Examples

use iai_callgrind::Bench;
fn my_teardown() {
    println!(
        "Place everything in this function you want to be executed after the execution of the \
         Command"
    );
}

let bench = Bench::new("some_id").teardown(my_teardown).clone();

assert!(bench.teardown.is_some())

Overwrite the teardown function from this BinaryBenchmark in a Bench

use iai_callgrind::{Bench, BinaryBenchmark};
fn binary_benchmark_teardown() {
    println!("teardown in BinaryBenchmark")
}

fn bench_teardown() {
    println!("teardown in Bench")
}

BinaryBenchmark::new("bench_binary")
    .teardown(binary_benchmark_teardown)
    .bench(Bench::new("some_id").teardown(bench_teardown));

Trait Implementations

impl Clone for BinaryBenchmark

fn clone(&self) -> BinaryBenchmark

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for BinaryBenchmark

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl From<&BinaryBenchmark> for BinaryBenchmark

fn from(value: &BinaryBenchmark) -> Self

Converts to this type from the input type.

impl From<&mut BinaryBenchmark> for BinaryBenchmark

fn from(value: &mut BinaryBenchmark) -> Self

Converts to this type from the input type.

impl PartialEq for BinaryBenchmark

fn eq(&self, other: &BinaryBenchmark) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl StructuralPartialEq for BinaryBenchmark