Struct Bench

source

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

Available on crate feature default only.

Expand description

low level api only: This struct mirrors the #[bench] and #[benches] attribute of a crate::binary_benchmark

Fields§

§id: BenchmarkId

The BenchmarkId used to uniquely identify this benchmark within a BinaryBenchmark

§commands: Vec<Command>

All Commands

§config: Option<InternalBinaryBenchmarkConfig>

An optional BinaryBenchmarkConfig

This field stores the internal representation of the BinaryBenchmarkConfig. Use BinaryBenchmarkConfig::into to generate the internal configuration from a BinaryBenchmarkConfig

§setup: Option<fn()>

The setup function to be executed before the Command is executed

§teardown: Option<fn()>

The teardown function to be executed after the Command is executed

Implementations§

source §

impl Bench

source

pub fn new<T>(id: T) -> Self
where T: Into<BenchmarkId>,

Create a new Bench with a unique BenchmarkId

If the provided BenchmarkId is invalid, iai-callgrind exits with an error.

§Scope of uniqueness of the `BenchmarkId`

The id needs to be unique within the same BinaryBenchmark

§Examples

The BenchmarkId can be created from any &str-like

use iai_callgrind::Bench;

let bench = Bench::new("my_unique_id");

but you can also provide the BenchmarkId

use iai_callgrind::{Bench, BenchmarkId};

let bench = Bench::new(BenchmarkId::new("my_unique_id"));

source

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

Add a BinaryBenchmarkConfig for this Bench

A Bench without a BinaryBenchmarkConfig behaves like having specified the default BinaryBenchmarkConfig. This BinaryBenchmarkConfig overwrites the values of a BinaryBenchmarkConfig specified at a higher level. See there for more details.

§Examples

use iai_callgrind::{Bench, BinaryBenchmarkConfig};

let bench = Bench::new("some_id").config(BinaryBenchmarkConfig::default().env("FOO", "BAR"));

source

pub fn command<T>(&mut self, command: T) -> &mut Self
where T: Into<Command>,

Add a Command to this Bench

A Bench with multiple Commands behaves exactly as the #[benches] attribute

§Errors

It is an error if a Bench does not contain any Commands, so this method or Bench::commands has to be called at least once.

§Examples

Suppose the crate’s binary is called my-echo:

use iai_callgrind::{Bench, Command};

let bench = Bench::new("some_id")
    .command(Command::new(env!("CARGO_BIN_EXE_my-echo")))
    .clone();

assert_eq!(bench.commands.len(), 1);

source

pub fn commands<I, T>(&mut self, commands: T) -> &mut Self
where I: Into<Command>, T: IntoIterator<Item = I>,

Add multiple Commands to this Bench

§Examples

Suppose the crate’s binary is called my-echo

use iai_callgrind::{Bench, Command};

let mut command = Command::new(env!("CARGO_BIN_EXE_my-echo"));

let echo_foo = command.clone().arg("foo").build();
let echo_bar = command.arg("bar").build();

let mut bench = Bench::new("some_id");
bench.commands([echo_foo, echo_bar]).clone();

assert_eq!(bench.commands.len(), 2);

source

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

Add a setup function to be executed before the Command is executed

This setup function overwrites the setup function of BinaryBenchmark. In the presence of a Sandbox, this function is executed in the sandbox.

§Examples

use iai_callgrind::Bench;

fn my_setup() {
    println!("Place everything in this function you want to be executed prior to the Command");
}

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

assert!(bench.setup.is_some())

Overwrite the setup function from a BinaryBenchmark

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));

source

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

Add a teardown function to be executed after the Command is executed

This teardown function overwrites the teardown function of BinaryBenchmark. In the presence of a Sandbox, this function is executed in the sandbox.

§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 mut bench = Bench::new("some_id");
bench.teardown(my_teardown);

assert!(bench.teardown.is_some())

Overwrite the teardown function from a BinaryBenchmark

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));

source

pub fn file<T>( &mut self, path: T, generator: fn(_: String) -> Result<Command, String>, ) -> Result<&mut Self, String>
where T: AsRef<Path>,

Add each line of a file as Command to this Bench using a generator function.

This method mirrors the file parameter of the #[benches] attribute as far as possible. In the low-level api you can achieve the same or more quickly yourself and this method exists for the sake of completeness (and convenience).

The file has to exist at the time you’re using this method and the file has to be encoded in UTF-8. The generator function tells us how to convert each line of the file into a Command.

§Notable differences to high-level api

If the file path in the high-level api is relative we interpret the path relative to the workspace root (and make it absolute). In this method we use the path AS IS.

§Errors

If the file is empty, cannot be opened for reading or a line in the file cannot be converted to a String. Also, the error from the generator is propagated. The errors containing the line number use a 0-indexed line number.

§Examples

Suppose your cargo’s binary is named my-echo and you want to convert a file with inputs benches/inputs into commands and each line is the only argument for your my-echo binary:

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

binary_benchmark_group!(
    name = my_group;
    benchmarks = |group: &mut BinaryBenchmarkGroup| {
        group.binary_benchmark(BinaryBenchmark::new("some_id")
            .bench(Bench::new("bench_id")
                .file("benches/inputs", |line| {
                    Ok(iai_callgrind::Command::new(env!("CARGO_BIN_EXE_my-echo"))
                        .arg(line)
                        .build())
                }).unwrap()
            )
        )
    }
);