pub struct Sandbox(/* private fields */);default only.Expand description
The Sandbox in which the setup, teardown and the Command are run
The Sandbox is a temporary directory which is created before the execution of the
setup and deleted after the
teardown. setup, the Command and teardown are executed
inside this temporary directory.
§Background and reasons for using a Sandbox
A Sandbox can help mitigating differences in benchmark results on different machines. As
long as $TMP_DIR is unset or set to /tmp, the temporary directory has a constant length on
unix machines (except android which uses /data/local/tmp). The directory itself
is created with a constant length but random name like /tmp/.a23sr8fk. It is not implausible
that an executable has different event counts just because the directory it is executed in has a
different length. For example, if a member of your project has set up the project in
/home/bob/workspace/our-project running the benchmarks in this directory, and the ci runs the
benchmarks in /runner/our-project, the event counts might differ. If possible, the benchmarks
should be run in an as constant as possible environment. Clearing the environment variables is
also such a counter-measure.
Other reasons for using a Sandbox are convenience, such as if you’re creating files during
setup and the Command run and don’t want to delete all the files manually. Or, more
importantly, if the Command is destructive and deletes files, it is usually safer to execute
such a Command in a temporary directory where it cannot do any harm to your or others file
systems during the benchmark runs.
§Sandbox cleanup
The changes the setup makes in this directory persist until the teardown has finished. So,
the Command can for example pick up any files created by the setup method. If run in a
Sandbox, the teardown usually doesn’t have to delete any files, because the whole
directory is deleted after its usage. There is an exception to the rule. If any of the files
inside the directory is not removable, for example because the permissions of a file don’t allow
the file to be deleted, then the whole directory persists. You can use the teardown to reset
all permission bits to be readable and writable, so the cleanup can succeed.
To simply copy fixtures or whole directories into the Sandbox use Sandbox::fixtures.
Implementations§
Source§impl Sandbox
impl Sandbox
Sourcepub fn new(enabled: bool) -> Self
pub fn new(enabled: bool) -> Self
Create a new Sandbox builder
Per default, a Command is not run in a Sandbox because setting up a Sandbox usually
involves some user interaction, for example copying fixtures into it with
Sandbox::fixtures.
The temporary directory is only created immediately before the setup and the Command
are executed.
§Examples
Enable the sandbox for all benchmarks
use iai_callgrind::{BinaryBenchmarkConfig, Sandbox, main};
main!(
config = BinaryBenchmarkConfig::default().sandbox(Sandbox::new(true));
binary_benchmark_groups = my_group
);Sourcepub fn fixtures<I, T>(&mut self, paths: T) -> &mut Self
pub fn fixtures<I, T>(&mut self, paths: T) -> &mut Self
Specify the directories and/or files you want to copy into the root of the Sandbox
The paths are interpreted relative to the workspace root as it is reported by cargo. In a
multi-crate project this is the directory with the top-level Cargo.toml. Otherwise, it is
simply the directory with your Cargo.toml file in it.
§Examples
Assuming you crate’s binary is called my-foo taking a file path as the first argument and
the fixtures directory is $WORKSPACE_ROOT/benches/fixtures containing a fixture
fix_1.txt:
use iai_callgrind::{binary_benchmark, BinaryBenchmarkConfig, Sandbox};
#[binary_benchmark]
#[bench::fix_1(
args = ("fix_1.txt"),
config = BinaryBenchmarkConfig::default()
.sandbox(Sandbox::new(true)
.fixtures(["benches/fixtures/fix_1.txt"])
)
)]
fn bench_with_fixtures(path: &str) -> iai_callgrind::Command {
iai_callgrind::Command::new(env!("CARGO_BIN_EXE_my-foo"))
.arg(path)
.build()
}