Struct LibraryBenchmarkConfig

Source

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

Available on crate feature default only.

Expand description

The main configuration of a library benchmark.

§Examples

use iai_callgrind::{LibraryBenchmarkConfig, main, Callgrind};
main!(
    config = LibraryBenchmarkConfig::default()
                .tool(Callgrind::with_args(["toggle-collect=something"]));
    library_benchmark_groups = some_group
);

Implementations§

Source §

impl LibraryBenchmarkConfig

Source

pub fn default_tool(&mut self, tool: ValgrindTool) -> &mut Self

Change the default tool to something different than callgrind

Any ValgrindTool is valid, however using cachegrind also requires to use client requests to produce correct metrics. The guide fully describes how to use cachegrind instead of callgrind.

§Example for dhat

use iai_callgrind::{
    main, LibraryBenchmarkConfig, ValgrindTool, library_benchmark_group, library_benchmark
};

#[library_benchmark]
fn bench_me() -> u64 {
    lib::some_func(10)
}

library_benchmark_group!(
   name = my_group;
   benchmarks = bench_me
);

main!(
    config = LibraryBenchmarkConfig::default()
        .default_tool(ValgrindTool::DHAT);
    library_benchmark_groups = my_group
);

§Example for using cachegrind as default tool on the fly

--instr-at-start=no is required to only measure the metrics between the two client request calls.

use iai_callgrind::{
    main, LibraryBenchmarkConfig, ValgrindTool, library_benchmark_group, library_benchmark,
    Cachegrind
};
use iai_callgrind::client_requests::cachegrind as cr;

#[library_benchmark(
    config = LibraryBenchmarkConfig::default()
        .default_tool(ValgrindTool::Cachegrind)
        .tool(Cachegrind::with_args(["--instr-at-start=no"]))
)]
fn bench_me() -> u64 {
    cr::start_instrumentation();
    let r = lib::some_func(10);
    cr::stop_instrumentation();
    r
}

library_benchmark_group!(
   name = my_group;
   benchmarks = bench_me
);

main!(library_benchmark_groups = my_group);

Source

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 crate::Callgrind::args

§Examples

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

use iai_callgrind::{main, LibraryBenchmarkConfig, Dhat};

main!(
    config = LibraryBenchmarkConfig::default()
        .valgrind_args(["--trace-children=no"])
        .tool(Dhat::default());
    library_benchmark_groups = my_group
);

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

use iai_callgrind::{main, LibraryBenchmarkConfig, Dhat};

main!(
    config = LibraryBenchmarkConfig::default()
        .valgrind_args(["--num-callers=25"])
        .tool(Dhat::with_args(["--num-callers=30"]));
    library_benchmark_groups = my_group
);

Source

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

Clear the environment variables before running a benchmark (Default: true)

§Examples

use iai_callgrind::{LibraryBenchmarkConfig, main};

main!(
    config = LibraryBenchmarkConfig::default().env_clear(false);
    library_benchmark_groups = some_group
);

Source

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

Add an environment variables which will be available in library benchmarks

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

§Examples

An example for a custom environment variable, available in all benchmarks:

use iai_callgrind::{LibraryBenchmarkConfig, main};

main!(
    config = LibraryBenchmarkConfig::default().env("FOO", "BAR");
    library_benchmark_groups = some_group
);

Source

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 which will be available in library benchmarks

See also LibraryBenchmarkConfig::env for more details.

§Examples

use iai_callgrind::{LibraryBenchmarkConfig, main};

main!(
    config =
        LibraryBenchmarkConfig::default()
            .envs([("MY_CUSTOM_VAR", "SOME_VALUE"), ("FOO", "BAR")]);
    library_benchmark_groups = some_group
);

Source

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 library 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::{LibraryBenchmarkConfig, main};

main!(
    config = LibraryBenchmarkConfig::default().pass_through_env("HOME");
    library_benchmark_groups = some_group
);

Source

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

§Examples

use iai_callgrind::{LibraryBenchmarkConfig, main};

main!(
    config = LibraryBenchmarkConfig::default().pass_through_envs(["HOME", "USER"]);
    library_benchmark_groups = some_group
);

Source

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

Add a configuration for a valgrind tool

Valid configurations are crate::Callgrind, crate::Cachegrind, crate::Dhat, crate::Memcheck, crate::Helgrind, crate::Drd, crate::Massif and crate::Bbv.

§Example

Run DHAT in addition to callgrind.

use iai_callgrind::{LibraryBenchmarkConfig, main, Dhat};

main!(
    config = LibraryBenchmarkConfig::default()
        .tool(Dhat::default());
    library_benchmark_groups = some_group
);

Source

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

Override previously defined configurations of valgrind tools

Usually, if specifying tool configurations with LibraryBenchmarkConfig::tool these tools are appended to the configuration of a LibraryBenchmarkConfig of higher-levels. Specifying a tool with this method overrides previously defined configurations.

§Examples

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

use iai_callgrind::{
    main, library_benchmark, library_benchmark_group, LibraryBenchmarkConfig, Memcheck,
    Massif, Dhat
};

#[library_benchmark(config = LibraryBenchmarkConfig::default()
    .tool_override(Memcheck::default())
)]
fn some_func() {}

library_benchmark_group!(
    name = some_group;
    benchmarks = some_func
);

main!(
    config = LibraryBenchmarkConfig::default()
        .tool(Dhat::default())
        .tool(Massif::default());
    library_benchmark_groups = some_group
);

Source

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, LibraryBenchmarkConfig, OutputFormat};
main!(
    config = LibraryBenchmarkConfig::default()
        .output_format(OutputFormat::default()
            .truncate_description(Some(200))
        );
    library_benchmark_groups = some_group
);