Struct CommandLineArgs

pub struct CommandLineArgs {

    pub filter: Option<BenchmarkFilter>,
    pub callgrind_args: Option<RawArgs>,
    pub save_summary: Option<SummaryFormat>,
    pub allow_aslr: Option<bool>,
    pub regression: Option<RegressionConfig>,
    pub regression_fail_fast: Option<bool>,
    pub save_baseline: Option<BaselineName>,
    pub baseline: Option<BaselineName>,
    pub load_baseline: Option<BaselineName>,
    pub output_format: OutputFormatKind,
    pub separate_targets: bool,
    pub home: Option<PathBuf>,
    pub nocapture: NoCapture,
    /* private fields */
}

Available on crate feature runner only.

The command line arguments the user provided after -- when running cargo bench

These arguments are not the command line arguments passed to iai-callgrind-runner. We collect the command line arguments in the iai-callgrind::main! macro without the binary as first argument, that’s why no_binary_name is set to true.

Fields

filter: Option<BenchmarkFilter>

If specified, only run benches containing this string in their names

Note that a benchmark name might differ from the benchmark file name.

callgrind_args: Option<RawArgs>

The raw arguments to pass through to Callgrind

This is a space separated list of command-line-arguments specified as if they were passed directly to valgrind.

Examples:

• –callgrind-args=–dump-instr=yes
• –callgrind-args=‘–dump-instr=yes –collect-systime=yes’

save_summary: Option<SummaryFormat>

Save a machine-readable summary of each benchmark run in json format next to the usual benchmark output

allow_aslr: Option<bool>

Allow ASLR (Address Space Layout Randomization)

If possible, ASLR is disabled on platforms that support it (linux, freebsd) because ASLR could noise up the callgrind cache simulation results a bit. Setting this option to true runs all benchmarks with ASLR enabled.

See also https://docs.kernel.org/admin-guide/sysctl/kernel.html?highlight=randomize_va_space#randomize-va-space

regression: Option<RegressionConfig>

Set performance regression limits for specific EventKinds

This is a , separate list of EventKind=limit (key=value) pairs with the limit being a positive or negative percentage. If positive, a performance regression check for this EventKind fails if the limit is exceeded. If negative, the regression check fails if the value comes below the limit. The EventKind is matched case-insensitive. For a list of valid EventKinds see the docs: https://docs.rs/iai-callgrind/latest/iai_callgrind/enum.EventKind.html

Examples: –regression=‘ir=0.0’ or –regression=‘ir=0, EstimatedCycles=10’

regression_fail_fast: Option<bool>

If true, the first failed performance regression check fails the whole benchmark run

This option requires --regression=... or IAI_CALLGRIND_REGRESSION=... to be present.

save_baseline: Option<BaselineName>

Compare against this baseline if present and then overwrite it

baseline: Option<BaselineName>

Compare against this baseline if present but do not overwrite it

load_baseline: Option<BaselineName>

Load this baseline as the new data set instead of creating a new one

output_format: OutputFormatKind

The terminal output format in default human-readable format or in machine-readable json format

The JSON Output Format

The json terminal output schema is the same as the schema with the --save-summary argument when saving to a summary.json file. All other output than the json output goes to stderr and only the summary output goes to stdout. When not printing pretty json, each line is a dictionary summarizing a single benchmark. You can combine all lines (benchmarks) into an array for example with jq

cargo bench -- --output-format=json | jq -s

which transforms {...}\n{...} into [{...},{...}]

separate_targets: bool

Separate iai-callgrind benchmark output files by target

The default output path for files created by iai-callgrind and valgrind during the benchmark is

target/iai/$PACKAGE_NAME/$BENCHMARK_FILE/$GROUP/$BENCH_FUNCTION.$BENCH_ID.

This can be problematic if you’re running the benchmarks not only for a single target because you end up comparing the benchmark runs with the wrong targets. Setting this option changes the default output path to

target/iai/$TARGET/$PACKAGE_NAME/$BENCHMARK_FILE/$GROUP/$BENCH_FUNCTION.$BENCH_ID

Although not as comfortable and strict, you could achieve a separation by target also with baselines and a combination of --save-baseline=$TARGET and --baseline=$TARGET if you prefer having all files of a single $BENCH in the same directory.

home: Option<PathBuf>

Specify the home directory of iai-callgrind benchmark output files

All output files are per default stored under the $PROJECT_ROOT/target/iai directory. This option lets you customize this home directory, and it will be created if it doesn’t exist.

nocapture: NoCapture

Don’t capture terminal output of benchmarks

Possible values are one of [true, false, stdout, stderr].

This option is currently restricted to the callgrind run of benchmarks. The output of additional tool runs like DHAT, Memcheck, … is still captured, to prevent showing the same output of benchmarks multiple times. Use IAI_CALLGRIND_LOG=info to also show captured and logged output.

If no value is given, the default missing value is true and doesn’t capture stdout and stderr. Besides true or false you can specify the special values stdout or stderr. If --nocapture=stdout is given, the output to stdout won’t be captured and the output to stderr will be discarded. Likewise, if --nocapture=stderr is specified, the output to stderr won’t be captured and the output to stdout will be discarded.

Trait Implementations

impl Args for CommandLineArgs

fn group_id() -> Option<Id>

Report the ArgGroup::id for this set of arguments

fn augment_args<'b>(__clap_app: Command) -> Command

Append to Command so it can instantiate Self.

fn augment_args_for_update<'b>(__clap_app: Command) -> Command

Append to Command so it can update self.

impl Clone for CommandLineArgs

fn clone(&self) -> CommandLineArgs

Returns a copy of the value.

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

Performs copy-assignment from source.

impl CommandFactory for CommandLineArgs

fn command<'b>() -> Command

Build a Command that can instantiate Self.

fn command_for_update<'b>() -> Command

Build a Command that can update self.

impl Debug for CommandLineArgs

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

Formats the value using the given formatter.

impl From<&CommandLineArgs> for Option<RegressionConfig>

fn from(value: &CommandLineArgs) -> Self

Converts to this type from the input type.

impl FromArgMatches for CommandLineArgs

fn from_arg_matches(__clap_arg_matches: &ArgMatches) -> Result<Self, Error>

Instantiate Self from ArgMatches, parsing the arguments as needed.

fn from_arg_matches_mut( __clap_arg_matches: &mut ArgMatches, ) -> Result<Self, Error>

Instantiate Self from ArgMatches, parsing the arguments as needed.

fn update_from_arg_matches( &mut self, __clap_arg_matches: &ArgMatches, ) -> Result<(), Error>

Assign values from ArgMatches to self.

fn update_from_arg_matches_mut( &mut self, __clap_arg_matches: &mut ArgMatches, ) -> Result<(), Error>

Assign values from ArgMatches to self.

impl Parser for CommandLineArgs

fn parse() -> Self

Parse from std::env::args_os(), exit on error

fn try_parse() -> Result<Self, Error>

Parse from std::env::args_os(), return Err on error.

fn parse_from<I, T>(itr: I) -> Self

where I: IntoIterator<Item = T>, T: Into<OsString> + Clone,

Parse from iterator, exit on error

fn try_parse_from<I, T>(itr: I) -> Result<Self, Error>

where I: IntoIterator<Item = T>, T: Into<OsString> + Clone,

Parse from iterator, return Err on error.

fn update_from<I, T>(&mut self, itr: I)

where I: IntoIterator<Item = T>, T: Into<OsString> + Clone,

Update from iterator, exit on error

fn try_update_from<I, T>(&mut self, itr: I) -> Result<(), Error>

where I: IntoIterator<Item = T>, T: Into<OsString> + Clone,

Update from iterator, return Err on error.