Struct BinaryBenchmarkConfig

pub struct BinaryBenchmarkConfig(/* private fields */);

Available on crate feature default only.

The configuration of a binary benchmark

The BinaryBenchmarkConfig can be specified at multiple levels and configures the benchmarks at this level. For example a BinaryBenchmarkConfig at (main)crate::main level configures all benchmarks. A configuration at group level configures all benchmarks in this group inheriting the configuration of the main level and if not specified otherwise overwrites the values of the main configuration if the option is specified in both BinaryBenchmarkConfigs. The deeper levels are the (#[binary_benchmark] attribute)crate::binary_benchmark, then #[bench] and the #[benches] attribute.

Examples

use iai_callgrind::{BinaryBenchmarkConfig, main};

main!(
    config = BinaryBenchmarkConfig::default().callgrind_args(["toggle-collect=something"]);
    binary_benchmark_groups = some_group
);

Implementations

impl BinaryBenchmarkConfig

pub fn raw_callgrind_args<I, T>(&mut self, args: T) -> &mut Self

where I: AsRef<str>, T: IntoIterator<Item = I>,

👎Deprecated: Please use callgrind_args instead

Pass arguments to valgrind’s callgrind

It’s not needed to pass the arguments with flags. Instead of --collect-atstart=no simply write collect-atstart=no.

See also Callgrind Command-line Options for a full overview of possible arguments.

Examples

use iai_callgrind::BinaryBenchmarkConfig;

BinaryBenchmarkConfig::default()
    .callgrind_args(["collect-atstart=no", "toggle-collect=some::path"]);

pub fn with_callgrind_args<I, T>(args: T) -> Self

where I: AsRef<str>, T: IntoIterator<Item = I>,

Create a new BinaryBenchmarkConfig with initial callgrind arguments

See also BinaryBenchmarkConfig::callgrind_args.

Examples

use iai_callgrind::{BinaryBenchmarkConfig, main};

main!(
    config =
        BinaryBenchmarkConfig::with_callgrind_args(["toggle-collect=something"]);
    binary_benchmark_groups = some_group
);

pub fn callgrind_args<I, T>(&mut self, args: T) -> &mut Self

where I: AsRef<str>, T: IntoIterator<Item = I>,

Pass arguments to valgrind’s callgrind

It’s not needed to pass the arguments with flags. Instead of --collect-atstart=no simply write collect-atstart=no.

See also Callgrind Command-line Options for a full overview of possible arguments.

Examples

use iai_callgrind::BinaryBenchmarkConfig;

BinaryBenchmarkConfig::default()
    .callgrind_args(["collect-atstart=no", "toggle-collect=some::path"]);

pub fn valgrind_args<I, T>(&mut self, args: T) -> &mut Self

where I: AsRef<str>, T: IntoIterator<Item = I>,

Pass valgrind arguments to all tools

Only core valgrind arguments are allowed.

These arguments can be overwritten by tool specific arguments for example with BinaryBenchmarkConfig::callgrind_args or crate::Tool::args.

Examples

Specify --trace-children=no for all configured tools (including callgrind):

use iai_callgrind::{main, BinaryBenchmarkConfig, Tool, ValgrindTool};

main!(
    config = BinaryBenchmarkConfig::default()
        .valgrind_args(["--trace-children=no"])
        .tool(Tool::new(ValgrindTool::DHAT));
    binary_benchmark_groups = my_group
);

Overwrite the valgrind argument --num-callers=25 for DHAT with --num-callers=30:

use iai_callgrind::{main, BinaryBenchmarkConfig, Tool, ValgrindTool};

main!(
    config = BinaryBenchmarkConfig::default()
        .valgrind_args(["--num-callers=25"])
        .tool(Tool::new(ValgrindTool::DHAT)
            .args(["--num-callers=30"])
        );
    binary_benchmark_groups = my_group
);

pub fn env<K, V>(&mut self, key: K, value: V) -> &mut Self

where K: Into<OsString>, V: Into<OsString>,

Add an environment variable to the Command

These environment variables are available independently of the setting of BinaryBenchmarkConfig::env_clear.

Examples

An example for a custom environment variable “FOO=BAR”:

use iai_callgrind::{main, BinaryBenchmarkConfig};

main!(
    config = BinaryBenchmarkConfig::default().env("FOO", "BAR");
    binary_benchmark_groups = my_group
);

pub fn envs<K, V, T>(&mut self, envs: T) -> &mut Self

where K: Into<OsString>, V: Into<OsString>, T: IntoIterator<Item = (K, V)>,

Add multiple environment variables to the Command

Examples

use iai_callgrind::{main, BinaryBenchmarkConfig};

main!(
    config = BinaryBenchmarkConfig::default().envs([("FOO", "BAR"),("BAR", "BAZ")]);
    binary_benchmark_groups = my_group
);

pub fn pass_through_env<K>(&mut self, key: K) -> &mut Self

where K: Into<OsString>,

Specify a pass-through environment variable

Usually, the environment variables before running a binary benchmark are cleared but specifying pass-through variables makes this environment variable available to the benchmark as it actually appeared in the root environment.

Pass-through environment variables are ignored if they don’t exist in the root environment.

Examples

Here, we chose to pass through the original value of the HOME variable:

use iai_callgrind::{main, BinaryBenchmarkConfig};

main!(
    config = BinaryBenchmarkConfig::default().pass_through_env("HOME");
    binary_benchmark_groups = my_group
);

pub fn pass_through_envs<K, T>(&mut self, envs: T) -> &mut Self

where K: Into<OsString>, T: IntoIterator<Item = K>,

Specify multiple pass-through environment variables

See also crate::BinaryBenchmarkConfig::pass_through_env.

Examples

use iai_callgrind::{main, BinaryBenchmarkConfig};

main!(
    config = BinaryBenchmarkConfig::default().pass_through_envs(["HOME", "USER"]);
    binary_benchmark_groups = my_group
);

pub fn env_clear(&mut self, value: bool) -> &mut Self

If false, don’t clear the environment variables before running the benchmark (Default: true)

Examples

use iai_callgrind::{main, BinaryBenchmarkConfig};

main!(
    config = BinaryBenchmarkConfig::default().env_clear(false);
    binary_benchmark_groups = my_group
);

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

where T: Into<PathBuf>,

Set the directory of the benchmarked binary (Default: Unchanged)

Unchanged means, in the case of running with the sandbox enabled, the root of the sandbox. In the case of running without sandboxing enabled, this’ll be the directory which cargo bench sets. If running the benchmark within the sandbox, and the path is relative then this new directory must be contained in the sandbox.

Examples

use iai_callgrind::{main, BinaryBenchmarkConfig};

main!(
    config = BinaryBenchmarkConfig::default().current_dir("/tmp");
    binary_benchmark_groups = my_group
);

and the following will change the current directory to fixtures assuming it is contained in the root of the sandbox

use iai_callgrind::{main, BinaryBenchmarkConfig, Sandbox};

main!(
    config = BinaryBenchmarkConfig::default()
        .sandbox(Sandbox::new(true))
        .current_dir("fixtures");
    binary_benchmark_groups = my_group
);

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

where T: Into<InternalExitWith>,

Set the expected exit status ExitWith of a benchmarked binary

Per default, the benchmarked binary is expected to succeed which is the equivalent of ExitWith::Success. But, if a benchmark is expected to fail, setting this option is required.

Examples

If the benchmark is expected to fail with a specific exit code, for example 100:

use iai_callgrind::{main, BinaryBenchmarkConfig, ExitWith};

main!(
    config = BinaryBenchmarkConfig::default().exit_with(ExitWith::Code(100));
    binary_benchmark_groups = my_group
);

If a benchmark is expected to fail, but the exit code doesn’t matter:

use iai_callgrind::{main, BinaryBenchmarkConfig, ExitWith};

main!(
    config = BinaryBenchmarkConfig::default().exit_with(ExitWith::Failure);
    binary_benchmark_groups = my_group
);

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

where T: Into<InternalFlamegraphConfig>,

Option to produce flamegraphs from callgrind output using the crate::FlamegraphConfig

Examples

use iai_callgrind::{main, BinaryBenchmarkConfig, FlamegraphConfig };

main!(
    config = BinaryBenchmarkConfig::default().flamegraph(FlamegraphConfig::default());
    binary_benchmark_groups = my_group
);

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

where T: Into<InternalRegressionConfig>,

Enable performance regression checks with a crate::RegressionConfig

Examples

use iai_callgrind::{main, BinaryBenchmarkConfig, RegressionConfig};

main!(
    config = BinaryBenchmarkConfig::default().regression(RegressionConfig::default());
    binary_benchmark_groups = my_group
);

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

where T: Into<InternalTool>,

Add a configuration to run a valgrind crate::Tool in addition to callgrind

Examples

use iai_callgrind::{main, BinaryBenchmarkConfig, Tool, ValgrindTool};

main!(
    config = BinaryBenchmarkConfig::default()
        .tool(
            Tool::new(ValgrindTool::DHAT)
        );
    binary_benchmark_groups = my_group
);

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

where I: Into<InternalTool>, T: IntoIterator<Item = I>,

Add multiple configurations to run valgrind crate::Tools in addition to callgrind

Examples

use iai_callgrind::{main, BinaryBenchmarkConfig, Tool, ValgrindTool};

main!(
    config = BinaryBenchmarkConfig::default()
        .tools(
            [
                Tool::new(ValgrindTool::DHAT),
                Tool::new(ValgrindTool::Massif)
            ]
        );
    binary_benchmark_groups = my_group
);

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

where T: Into<InternalTool>,

Override previously defined configurations of valgrind crate::Tools

See also crate::LibraryBenchmarkConfig::tool_override for more details.

Example

The following will run DHAT and Massif (and the default callgrind) for all benchmarks in main! besides for foo which will just run Memcheck (and callgrind).

use iai_callgrind::{
    binary_benchmark, binary_benchmark_group, BinaryBenchmarkConfig, main, Tool,
    ValgrindTool
};

#[binary_benchmark]
#[bench::some(
    config = BinaryBenchmarkConfig::default()
        .tool_override(Tool::new(ValgrindTool::Memcheck))
)]
fn bench_binary() -> iai_callgrind::Command {
    iai_callgrind::Command::new(env!("CARGO_BIN_EXE_my-exe"))
}

binary_benchmark_group!(
    name = my_group;
    benchmarks = bench_binary
);

main!(
    config = BinaryBenchmarkConfig::default()
        .tools(
            [
                Tool::new(ValgrindTool::DHAT),
                Tool::new(ValgrindTool::Massif)
            ]
        );
    binary_benchmark_groups = my_group
);

pub fn tools_override<I, T>(&mut self, tools: T) -> &mut Self

where I: Into<InternalTool>, T: IntoIterator<Item = I>,

Override previously defined configurations of valgrind crate::Tools

See also crate::LibraryBenchmarkConfig::tool_override for more details.

Example

The following will run DHAT (and the default callgrind) for all benchmarks in main! besides for foo which will run Massif and Memcheck (and callgrind).

use iai_callgrind::{
    binary_benchmark, binary_benchmark_group, BinaryBenchmarkConfig, main, Tool,
    ValgrindTool
};

#[binary_benchmark]
#[bench::some(
    config = BinaryBenchmarkConfig::default()
        .tools_override([
            Tool::new(ValgrindTool::Massif),
            Tool::new(ValgrindTool::Memcheck),
        ])
)]
fn bench_binary() -> iai_callgrind::Command {
    iai_callgrind::Command::new(env!("CARGO_BIN_EXE_my-exe"))
}

binary_benchmark_group!(
    name = my_group;
    benchmarks = bench_binary
);

main!(
    config = BinaryBenchmarkConfig::default()
        .tool(
            Tool::new(ValgrindTool::DHAT),
        );
    binary_benchmark_groups = my_group
);

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

where T: Into<InternalSandbox>,

Configure benchmarks to run in a Sandbox (Default: false)

If specified, we create a temporary directory in which the setup and teardown functions of the #[binary_benchmark] (#[bench], #[benches]) and the Command itself are run.

A good reason for using a temporary directory as workspace is, that the length of the path where a benchmark is executed may have an influence on the benchmark results. For example, running the benchmark in your repository /home/me/my/repository and someone else’s repository located under /home/someone/else/repository may produce different results only because the length of the first path is shorter. To run benchmarks as deterministic as possible across different systems, the length of the path should be the same wherever the benchmark is executed. This crate ensures this property by using the tempfile crate which creates the temporary directory in /tmp with a random name of fixed length like /tmp/.tmp12345678. This ensures that the length of the directory will be the same on all unix hosts where the benchmarks are run.

Examples

use iai_callgrind::{main, BinaryBenchmarkConfig, Sandbox};

main!(
    config = BinaryBenchmarkConfig::default().sandbox(Sandbox::new(true));
    binary_benchmark_groups = my_group
);

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

where T: Into<InternalOutputFormat>,

Configure the crate::OutputFormat of the terminal output of Iai-Callgrind

Examples

use iai_callgrind::{main, BinaryBenchmarkConfig, OutputFormat};
main!(
    config = BinaryBenchmarkConfig::default()
        .output_format(OutputFormat::default()
            .truncate_description(Some(200))
        );
    binary_benchmark_groups = some_group
);

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

Execute the setup in parallel to the Command.

See also Command::setup_parallel

Examples

use std::time::Duration;
use std::net::{SocketAddr, TcpListener};
use std::thread;
use iai_callgrind::{
    binary_benchmark_group, binary_benchmark, main, BinaryBenchmarkConfig, Command,
    Delay, DelayKind
};

fn setup_tcp_server() {
    thread::sleep(Duration::from_millis(300));
    let _listener = TcpListener::bind("127.0.0.1:31000".parse::<SocketAddr>().unwrap()).unwrap();
    thread::sleep(Duration::from_secs(1));
}

#[binary_benchmark]
#[bench::delay(
    setup = setup_tcp_server(),
    config = BinaryBenchmarkConfig::default()
        .setup_parallel(true)
)]
fn bench_binary() -> iai_callgrind::Command {
    Command::new(env!("CARGO_BIN_EXE_my-echo"))
        .delay(
            Delay::new(
                DelayKind::TcpConnect("127.0.0.1:31000".parse::<SocketAddr>().unwrap()))
                .timeout(Duration::from_millis(500))
        ).build()
}

binary_benchmark_group!(name = delay; benchmarks = bench_binary);
main!(binary_benchmark_groups = delay);

Trait Implementations

impl AsRef<BinaryBenchmarkConfig> for BinaryBenchmarkConfig

fn as_ref(&self) -> &InternalBinaryBenchmarkConfig

Converts this type into a shared reference of the (usually inferred) input type.

impl Clone for BinaryBenchmarkConfig

fn clone(&self) -> BinaryBenchmarkConfig

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for BinaryBenchmarkConfig

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

Formats the value using the given formatter.

impl Default for BinaryBenchmarkConfig

fn default() -> BinaryBenchmarkConfig

Returns the “default value” for a type.

impl From<&BinaryBenchmarkConfig> for InternalBinaryBenchmarkConfig

fn from(value: &BinaryBenchmarkConfig) -> Self

Converts to this type from the input type.

impl From<&mut BinaryBenchmarkConfig> for InternalBinaryBenchmarkConfig

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

Converts to this type from the input type.

impl From<BinaryBenchmarkConfig> for InternalBinaryBenchmarkConfig

fn from(value: BinaryBenchmarkConfig) -> Self

Converts to this type from the input type.