Struct iai_callgrind::LibraryBenchmarkConfig

source ·

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

Expand description

The main configuration of a library benchmark.

See LibraryBenchmarkConfig::raw_callgrind_args for more details.

Examples

main!(
    config = LibraryBenchmarkConfig::default()
                .raw_callgrind_args(["toggle-collect=something"]);
    library_benchmark_groups = some_group
);

Implementations§

source §

impl LibraryBenchmarkConfig

source

pub fn with_raw_callgrind_args<I, T>(args: T) -> Selfwhere I: AsRef<str>, T: IntoIterator<Item = I>,

Create a new LibraryBenchmarkConfig with raw callgrind arguments

pub fn raw_callgrind_args<I, T>(&mut self, args: T) -> &mut Selfwhere I: AsRef<str>, T: IntoIterator<Item = I>,

Add callgrind arguments to this LibraryBenchmarkConfig

The arguments don’t need to start with a flag: --toggle-collect=some or toggle-collect=some are both understood.

Not all callgrind arguments are understood by iai-callgrind or cause problems in iai-callgrind if they would be applied. iai-callgrind will issue a warning in such cases. Some of the defaults can be overwritten. The default settings are:

--I1=32768,8,64
--D1=32768,8,64
--LL=8388608,16,64
--cache-sim=yes (can’t be changed)
--toggle-collect=*BENCHMARK_FILE::BENCHMARK_FUNCTION (this first toggle can’t be changed)
--collect-atstart=no (overwriting this setting will have no effect)
--compress-pos=no
--compress-strings=no

Note that toggle-collect is an array and the entry point for library benchmarks is the benchmark function. This default toggle switches event counting on when entering this benchmark function and off when leaving it. So, additional toggles for example matching a function within the benchmark function will switch the event counting off when entering the matched function and on again when leaving it!

Examples

main!(
    config = LibraryBenchmarkConfig::default()
                .raw_callgrind_args(["toggle-collect=something"]);
    library_benchmark_groups = some_group
);

source

pub fn raw_callgrind_args_iter<I, T>(&mut self, args: T) -> &mut Selfwhere I: AsRef<str>, T: IntoIterator<Item = I>,

Add elements of an iterator over callgrind arguments to this LibraryBenchmarkConfig

Examples

main!(
    config = LibraryBenchmarkConfig::default()
                .raw_callgrind_args_iter(["toggle-collect=something"].iter());
    library_benchmark_groups = some_group
);

source

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

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

Examples

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 Selfwhere 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:

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

source

pub fn envs<K, V, T>(&mut self, envs: T) -> &mut Selfwhere 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

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 Selfwhere 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:

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 Selfwhere K: Into<OsString>, T: IntoIterator<Item = K>,

Specify multiple pass-through environment variables

Examples

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

source

pub fn flamegraph<T>(&mut self, config: T) -> &mut Selfwhere T: Into<InternalFlamegraphConfig>,

Option to produce flamegraphs from callgrind output using the FlamegraphConfig

Examples

use iai_callgrind::{LibraryBenchmarkConfig, main, FlamegraphConfig};
main!(
    config = LibraryBenchmarkConfig::default().flamegraph(FlamegraphConfig::default());
    library_benchmark_groups = some_group
);