Struct iai_callgrind::Run
source · pub struct Run(/* private fields */);
Expand description
Run
let’s you set up and configure a benchmark run of a binary
Implementations§
source§impl Run
impl Run
sourcepub fn with_cmd<T, U>(cmd: T, arg: U) -> Self
pub fn with_cmd<T, U>(cmd: T, arg: U) -> Self
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"])));
}
);
sourcepub fn with_cmd_args<T, I, U>(cmd: T, args: U) -> Self
pub fn with_cmd_args<T, I, U>(cmd: T, args: U) -> Self
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"]),
]));
}
);
sourcepub fn with_arg<T>(arg: T) -> Selfwhere
T: Into<InternalArg>,
pub fn with_arg<T>(arg: T) -> Selfwhere
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"])));
}
);
sourcepub fn with_args<I, T>(args: T) -> Self
pub fn with_args<I, T>(args: T) -> Self
Create a new Run
with multiple Arg
Specifying multiple Arg
arguments is actually just a short-hand for specifying multiple
Run
s 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"])
]));
}
);
sourcepub fn arg<T>(&mut self, arg: T) -> &mut Selfwhere
T: Into<InternalArg>,
pub fn arg<T>(&mut self, arg: T) -> &mut Selfwhere
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"]))
);
}
);
sourcepub fn args<I, T>(&mut self, args: T) -> &mut Self
pub fn args<I, T>(&mut self, args: T) -> &mut Self
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"])
])
);
}
);
sourcepub fn env<K, V>(&mut self, key: K, value: V) -> &mut Self
pub fn env<K, V>(&mut self, key: K, value: V) -> &mut Self
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")
);
}
);
sourcepub fn envs<K, V, T>(&mut self, envs: T) -> &mut Self
pub fn envs<K, V, T>(&mut self, envs: T) -> &mut Self
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")])
);
}
);
sourcepub fn pass_through_env<K>(&mut self, key: K) -> &mut Self
pub fn pass_through_env<K>(&mut self, key: K) -> &mut Self
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")
);
}
);
sourcepub fn pass_through_envs<K, T>(&mut self, envs: T) -> &mut Self
pub fn pass_through_envs<K, T>(&mut self, envs: T) -> &mut Self
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"])
);
}
);
sourcepub fn env_clear(&mut self, value: bool) -> &mut Self
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)
);
}
);
sourcepub fn current_dir<T>(&mut self, value: T) -> &mut Self
pub fn current_dir<T>(&mut self, value: T) -> &mut Self
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")
);
}
);
sourcepub fn entry_point<T>(&mut self, value: T) -> &mut Self
pub fn entry_point<T>(&mut self, value: T) -> &mut Self
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")
);
}
);
sourcepub fn exit_with<T>(&mut self, value: T) -> &mut Selfwhere
T: Into<InternalExitWith>,
pub fn exit_with<T>(&mut self, value: T) -> &mut Selfwhere
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)
);
}
);
sourcepub fn raw_callgrind_args<I, T>(&mut self, args: T) -> &mut Self
pub fn raw_callgrind_args<I, T>(&mut self, args: T) -> &mut Self
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"])
);
}
);
sourcepub fn flamegraph<T>(&mut self, config: T) -> &mut Selfwhere
T: Into<InternalFlamegraphConfig>,
pub fn flamegraph<T>(&mut self, config: T) -> &mut Selfwhere
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())
);
}
);
sourcepub fn regression<T>(&mut self, config: T) -> &mut Selfwhere
T: Into<InternalRegressionConfig>,
pub fn regression<T>(&mut self, config: T) -> &mut Selfwhere
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())
);
}
);
sourcepub fn tool<T>(&mut self, tool: T) -> &mut Selfwhere
T: Into<InternalTool>,
pub fn tool<T>(&mut self, tool: T) -> &mut Selfwhere
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),
)
);
}
);
sourcepub fn tools<I, T>(&mut self, tools: T) -> &mut Self
pub fn tools<I, T>(&mut self, tools: T) -> &mut Self
Add multiple configurations to run valgrind crate::Tool
s 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),
])
);
}
);
sourcepub fn tool_override<T>(&mut self, tool: T) -> &mut Selfwhere
T: Into<InternalTool>,
pub fn tool_override<T>(&mut self, tool: T) -> &mut Selfwhere
T: Into<InternalTool>,
Override previously defined configurations of valgrind crate::Tool
s
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
);
sourcepub fn tools_override<I, T>(&mut self, tools: T) -> &mut Self
pub fn tools_override<I, T>(&mut self, tools: T) -> &mut Self
Override previously defined configurations of valgrind crate::Tool
s
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
);