Struct Sandbox

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

Available on crate feature default only.

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

impl Sandbox

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
);

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

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

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()
}

Trait Implementations

impl AsRef<Sandbox> for Sandbox

fn as_ref(&self) -> &InternalSandbox

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

impl Clone for Sandbox

fn clone(&self) -> Sandbox

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Sandbox

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

Formats the value using the given formatter.

impl From<&Sandbox> for InternalSandbox

fn from(value: &Sandbox) -> Self

Converts to this type from the input type.

impl From<&mut Sandbox> for InternalSandbox

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

Converts to this type from the input type.

impl From<Sandbox> for InternalSandbox

fn from(value: Sandbox) -> Self

Converts to this type from the input type.