Struct BenchmarkId

source

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

Available on crate feature default only.

Expand description

low level api only: Create a new benchmark id

Implementations§

source §

impl BenchmarkId

source

pub fn with_parameter<T, P>(id: T, parameter: P) -> Self
where T: AsRef<str>, P: Display,

Convenience method to create a BenchmarkId with a parameter in the low level api

The parameter is simply appended to the id with an underscore, so BenchmarkId::with_parameter("some", 1) is equivalent to BenchmarkId::new("some_1")

§Examples

use iai_callgrind::BenchmarkId;

let new_id = BenchmarkId::new("prefix_1");
let with_parameter = BenchmarkId::with_parameter("prefix", 1);
assert_eq!(new_id, with_parameter);

use iai_callgrind::{binary_benchmark_group,BenchmarkId, BinaryBenchmark, Bench, Command};
use std::ffi::OsStr;

binary_benchmark_group!(
    name = low_level_group;
    benchmarks = |group: &mut BinaryBenchmarkGroup| {
        let mut binary_benchmark = BinaryBenchmark::new("some_id");
        for arg in 0..10 {
            let id = BenchmarkId::with_parameter("prefix", arg);
            binary_benchmark.bench(
                Bench::new(id)
                    .command(
                        Command::new("echo").arg(arg.to_string()).build()
                    )
            );
        }
        group.binary_benchmark(binary_benchmark);
    }
);

source

pub fn new<T>(id: T) -> Self
where T: Into<String>,

Create a new BenchmarkId

BenchmarkIds can be created from any string-like input. See BenchmarkId::validate for ids which are considered valid.

§Examples

use iai_callgrind::BenchmarkId;

let id = BenchmarkId::new("my_id");

assert!(id.validate().is_ok());

source

pub fn validate(&self) -> Result<(), String>

Returns ok if this BenchmarkId is valid

An id should be short, descriptive besides being unique. The requirements for the uniqueness differ for the structs where a BenchmarkId is used and is further described there.

We use a minimal subset of rust’s identifiers. A valid BenchmarkId starts with an ascii alphabetic letter [a-zA-Z] or underscore [_]. All following characters can be an ascii alphabetic letter, underscore or a digit [0-9]. At least one valid character must be present.

The BenchmarkId is used by iai-callgrind as file and directory name for the output files of the benchmarks. Therefore, the limit for an id is chosen to be 120 bytes. This is a calculation with some headroom. There are file systems which do not even allow 255 bytes. If you’re working on such a peculiar file system, you have to restrict your ids to even fewer bytes which is floor(MAX_LENGTH/2) - 1. Leaving the maximum bytes aside, the best IDs are simple, short and descriptive.

Usually, it is not necessary to call this function, since we already check the validity of benchmark ids prior to the execution of the benchmark runner. But if your ids come from an untrusted source you can use this method for more immediate feedback.

§Errors

This function will return an error describing the source of the error if the id is invalid

§Examples

use iai_callgrind::BenchmarkId;

assert!(BenchmarkId::new("").validate().is_err());
assert!(BenchmarkId::new("0a").validate().is_err());
assert!(BenchmarkId::new("id with spaces").validate().is_err());
assert!(BenchmarkId::new("path/to").validate().is_err());
assert!(BenchmarkId::new("no::module::too").validate().is_err());

assert!(BenchmarkId::new("_").validate().is_ok());
assert!(BenchmarkId::new("abc").validate().is_ok());
assert!(BenchmarkId::new("a9").validate().is_ok());
assert!(BenchmarkId::new("z_").validate().is_ok());
assert!(BenchmarkId::new("some_id").validate().is_ok());