Struct iai_callgrind::Run

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

Available on crate feature default only.

Run let’s you set up and configure a benchmark run of a binary

Implementations

impl Run

pub fn with_cmd<T, U>(cmd: T, arg: U) -> Self

where T: AsRef<str>, U: Into<InternalArg>,

Create a new Run with a cmd and Arg

A cmd specified here overwrites a cmd at group level.

Unlike to a cmd specified at group level, there is no auto-discovery of the executables of a crate, so a crate’s binary (say my-exe) has to be specified with env!("CARGO_BIN_EXE_my-exe").

Although not the main purpose of iai-callgrind, it’s possible to benchmark any executable in the PATH or specified with an absolute path.

Examples

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

binary_benchmark_group!(
    name = my_group;
    benchmark = |group: &mut BinaryBenchmarkGroup| {
        // Usually you should use `env!("CARGO_BIN_EXE_my-exe")` if `my-exe` is a binary
        // of your crate
        group.bench(Run::with_cmd("/path/to/my-exe", Arg::new("foo", &["foo"])));
    }
);

pub fn with_cmd_args<T, I, U>(cmd: T, args: U) -> Self

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

Create a new Run with a cmd and multiple Arg

See also Run::with_cmd

Examples

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

binary_benchmark_group!(
    name = my_group;
    benchmark = |group: &mut BinaryBenchmarkGroup| {
        group.bench(Run::with_cmd_args("/path/to/my-exe", [
            Arg::empty("empty foo"),
            Arg::new("foo", &["foo"]),
        ]));
    }
);

pub fn with_arg<T>(arg: T) -> Self

where T: Into<InternalArg>,

Create a new Run with an Arg

If a cmd is already specified at group level, there is no need to specify a cmd again (for example with Run::with_cmd). This method let’s you specify a single Arg to run with the cmd specified at group level.

Examples

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

binary_benchmark_group!(
    name = my_group;
    benchmark = |"my-exe", group: &mut BinaryBenchmarkGroup| {
        group.bench(Run::with_arg(Arg::new("foo", &["foo"])));
    }
);

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

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

Create a new Run with multiple Arg

Specifying multiple Arg arguments is actually just a short-hand for specifying multiple Runs with the same configuration and environment variables.

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

fn func1(group1: &mut BinaryBenchmarkGroup) {
    group1.bench(Run::with_args([
        Arg::empty("empty foo"),
        Arg::new("foo", &["foo"]),
    ]));
}

// This is actually the same as above in group1
fn func2(group2: &mut BinaryBenchmarkGroup) {
    group2.bench(Run::with_arg(Arg::empty("empty foo")));
    group2.bench(Run::with_arg(Arg::new("foo", &["foo"])));
}

See also Run::with_arg.

Examples

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

binary_benchmark_group!(
    name = my_group;
    benchmark = |"my-exe", group: &mut BinaryBenchmarkGroup| {
        group.bench(Run::with_args([
            Arg::empty("empty foo"),
            Arg::new("foo", &["foo"])
        ]));
    }
);

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

where T: Into<InternalArg>,

Add an additional Arg to the current Run

See also Run::with_args for more details about a Run with multiple Arg arguments.

Examples

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

binary_benchmark_group!(
    name = my_group;
    benchmark = |"my-exe", group: &mut BinaryBenchmarkGroup| {
        group.bench(
            Run::with_arg(Arg::empty("empty foo"))
                .arg(Arg::new("foo", &["foo"]))
        );
    }
);

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

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

Add multiple additional Arg arguments to the current Run

See also Run::with_args for more details about a Run with multiple Arg arguments.

Examples

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

binary_benchmark_group!(
    name = my_group;
    benchmark = |"my-exe", group: &mut BinaryBenchmarkGroup| {
        group.bench(
            Run::with_arg(Arg::empty("empty foo"))
                .args([
                    Arg::new("foo", &["foo"]),
                    Arg::new("bar", &["bar"])
            ])
        );
    }
);

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

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

Add an environment variable available in this Run

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

Examples

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

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

binary_benchmark_group!(
    name = my_group;
    benchmark = |"my-exe", group: &mut BinaryBenchmarkGroup| {
        group.bench(
            Run::with_arg(Arg::empty("empty foo")).env("FOO", "BAR")
        );
    }
);

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 variable available in this Run

Examples

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

binary_benchmark_group!(
    name = my_group;
    benchmark = |"my-exe", group: &mut BinaryBenchmarkGroup| {
        group.bench(
            Run::with_arg(Arg::empty("empty foo"))
                .envs([("FOO", "BAR"), ("BAR", "BAZ")])
        );
    }
);

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

where K: Into<OsString>,

Specify a pass-through environment variable

See also BinaryBenchmarkConfig::pass_through_env

Examples

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

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

binary_benchmark_group!(
    name = my_group;
    benchmark = |"my-exe", group: &mut BinaryBenchmarkGroup| {
        group.bench(
            Run::with_arg(Arg::empty("empty foo"))
                .pass_through_env("HOME")
        );
    }
);

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 BinaryBenchmarkConfig::pass_through_env.

Examples

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

binary_benchmark_group!(
    name = my_group;
    benchmark = |"my-exe", group: &mut BinaryBenchmarkGroup| {
        group.bench(
            Run::with_arg(Arg::empty("empty foo"))
                .pass_through_envs(["HOME", "USER"])
        );
    }
);

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::{binary_benchmark_group, Arg, BinaryBenchmarkGroup, Run};

binary_benchmark_group!(
    name = my_group;
    benchmark = |"my-exe", group: &mut BinaryBenchmarkGroup| {
        group.bench(
            Run::with_arg(Arg::empty("empty foo"))
                .env_clear(false)
        );
    }
);

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

where T: Into<PathBuf>,

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

See also BinaryBenchmarkConfig::current_dir

Examples

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

binary_benchmark_group!(
    name = my_group;
    benchmark = |"my-exe", group: &mut BinaryBenchmarkGroup| {
        group.bench(
            Run::with_arg(Arg::empty("empty foo"))
                .current_dir("/tmp")
        );
    }
);

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

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

binary_benchmark_group!(
    name = my_group;
    config = BinaryBenchmarkConfig::default().fixtures(Fixtures::new("fixtures"));
    benchmark = |"my-exe", group: &mut BinaryBenchmarkGroup| {
        group.bench(
            Run::with_arg(Arg::empty("empty foo"))
                .current_dir("fixtures")
        );
    }
);

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

where T: Into<String>,

Set the start and entry point for event counting of the binary benchmark run

See also BinaryBenchmarkConfig::entry_point.

Examples

The entry_point could look like my_exe::main for a binary with the name my-exe (Note that hyphens are replaced with an underscore).

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

binary_benchmark_group!(
    name = my_group;
    benchmark = |"my-exe", group: &mut BinaryBenchmarkGroup| {
        group.bench(
            Run::with_arg(Arg::empty("empty foo"))
                .entry_point("my_exe::main")
        );
    }
);

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

See also BinaryBenchmarkConfig::exit_with

Examples

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

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

binary_benchmark_group!(
    name = my_group;
    benchmark = |"my-exe", group: &mut BinaryBenchmarkGroup| {
        group.bench(
            Run::with_arg(Arg::empty("empty foo"))
                .exit_with(ExitWith::Code(100))
        );
    }
);

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

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

binary_benchmark_group!(
    name = my_group;
    benchmark = |"my-exe", group: &mut BinaryBenchmarkGroup| {
        group.bench(
            Run::with_arg(Arg::empty("empty foo"))
                .exit_with(ExitWith::Failure)
        );
    }
);

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

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

Pass arguments to valgrind’s callgrind at Run level

See also BinaryBenchmarkConfig::raw_callgrind_args

Examples

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

binary_benchmark_group!(
    name = my_group;
    benchmark = |"my-exe", group: &mut BinaryBenchmarkGroup| {
        group.bench(
            Run::with_arg(Arg::empty("empty foo"))
                .raw_callgrind_args(["collect-atstart=no", "toggle-collect=some::path"])
        );
    }
);

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

See also BinaryBenchmarkConfig::flamegraph

Examples

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

binary_benchmark_group!(
    name = my_group;
    benchmark = |"my-exe", group: &mut BinaryBenchmarkGroup| {
        group.bench(
            Run::with_arg(Arg::empty("empty foo"))
                .flamegraph(FlamegraphConfig::default())
        );
    }
);

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

where T: Into<InternalRegressionConfig>,

Enable performance regression checks with a crate::RegressionConfig

See also BinaryBenchmarkConfig::regression

Examples

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

binary_benchmark_group!(
    name = my_group;
    benchmark = |"my-exe", group: &mut BinaryBenchmarkGroup| {
        group.bench(
            Run::with_arg(Arg::empty("empty foo"))
                .regression(RegressionConfig::default())
        );
    }
);

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::{
    binary_benchmark_group, Arg, BinaryBenchmarkGroup, Run, Tool, ValgrindTool
};

binary_benchmark_group!(
    name = my_group;
    benchmark = |"my-exe", group: &mut BinaryBenchmarkGroup| {
        group.bench(
            Run::with_arg(Arg::empty("empty foo"))
                .tool(
                    Tool::new(ValgrindTool::DHAT),
                )
        );
    }
);

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::{
    binary_benchmark_group, Arg, BinaryBenchmarkGroup, Run, Tool, ValgrindTool
};

binary_benchmark_group!(
    name = my_group;
    benchmark = |"my-exe", group: &mut BinaryBenchmarkGroup| {
        group.bench(
            Run::with_arg(Arg::empty("empty foo"))
                .tools([
                    Tool::new(ValgrindTool::DHAT),
                    Tool::new(ValgrindTool::Massif),
                ])
        );
    }
);

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 BinaryBenchmarkConfig::tool_override.

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_group, Run, BinaryBenchmarkConfig, main, Tool, ValgrindTool, Arg
};

binary_benchmark_group!(
    name = my_group;
    benchmark = |"my-exe", group: &mut BinaryBenchmarkGroup| {
        group.bench(
            Run::with_arg(Arg::new("foo", &["foo"]))
                .tool_override(Tool::new(ValgrindTool::Memcheck))
        );
    }
);

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 BinaryBenchmarkConfig::tools_override.

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_group, Run, BinaryBenchmarkConfig, main, Tool, ValgrindTool, Arg
};

binary_benchmark_group!(
    name = my_group;
    benchmark = |"my-exe", group: &mut BinaryBenchmarkGroup| {
        group.bench(
            Run::with_arg(Arg::new("foo", &["foo"]))
                .tools_override([
                    Tool::new(ValgrindTool::Massif),
                    Tool::new(ValgrindTool::Memcheck),
                ])
        );
    }
);

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

Trait Implementations

impl AsRef<Run> for Run

fn as_ref(&self) -> &Run

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

impl Clone for Run

fn clone(&self) -> Run

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Run

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

Formats the value using the given formatter.

impl Default for Run

fn default() -> Run

Returns the “default value” for a type.

impl From<&Run> for InternalRun

fn from(value: &Run) -> Self

Converts to this type from the input type.

impl From<&mut Run> for InternalRun

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

Converts to this type from the input type.

impl From<Run> for InternalRun

fn from(value: Run) -> Self

Converts to this type from the input type.