请注意，setup和teardown参数与#[library_benchmark]、#[bench]和#[benches]中的参数不同。它们接受表达式或函数调用，如setup = group_setup_function()。此外，这些setup和teardown函数不会被上述任何属性覆盖。

比较基准测试函数

通过可选的library_benchmark_group!参数compare_by_id（compare_by_id的默认值为false）支持比较基准测试函数。只有具有相同id的基准测试才会比较，这允许突出显示不需要比较的案例。在以下示例中，除了与上次运行进行比较之外，还将case_3和multiple基准测试相互比较。

use iai_callgrind::{library_benchmark, library_benchmark_group};
use std::hint::black_box;
use my_lib::bubble_sort;

#[library_benchmark]
#[bench::case_3(vec![1, 2, 3])]
#[benches::multiple(args = [vec![1, 2], vec![1, 2, 3, 4]])]
fn bench_bubble_sort_best_case(input: Vec<i32>) -> Vec<i32> {
    black_box(bubble_sort(input))
}

#[library_benchmark]
#[bench::case_3(vec![3, 2, 1])]
#[benches::multiple(args = [vec![2, 1], vec![4, 3, 2, 1]])]
fn bench_bubble_sort_worst_case(input: Vec<i32>) -> Vec<i32> {
    black_box(bubble_sort(input))
}

library_benchmark_group!(
    name = bench_bubble_sort;
    compare_by_id = true;
    benchmarks = bench_bubble_sort_best_case, bench_bubble_sort_worst_case
);

注意，如果compare_by_id为true，则所有基准测试函数都将相互比较，因此您不需要在每个比较组中限制为两个基准测试函数。

以下是上述示例输出的精选摘录，以了解发生了什么

test_lib_bench_compare::bubble_sort_compare::bench_bubble_sort_best_case case_3:vec! [1, 2, 3]
  Instructions:                  94|N/A             (*********)
  L1 Hits:                      124|N/A             (*********)
  L2 Hits:                        0|N/A             (*********)
  RAM Hits:                       4|N/A             (*********)
  Total read+write:             128|N/A             (*********)
  Estimated Cycles:             264|N/A             (*********)
test_lib_bench_compare::bubble_sort_compare::bench_bubble_sort_worst_case case_3:vec! [3, 2, 1]
  Instructions:                 103|N/A             (*********)
  L1 Hits:                      138|N/A             (*********)
  L2 Hits:                        0|N/A             (*********)
  RAM Hits:                       5|N/A             (*********)
  Total read+write:             143|N/A             (*********)
  Estimated Cycles:             313|N/A             (*********)
  Comparison with bench_bubble_sort_best_case case_3:vec! [1, 2, 3]
  Instructions:                  94|103             (-8.73786%) [-1.09574x]
  L1 Hits:                      124|138             (-10.1449%) [-1.11290x]
  L2 Hits:                        0|0               (No change)
  RAM Hits:                       4|5               (-20.0000%) [-1.25000x]
  Total read+write:             128|143             (-10.4895%) [-1.11719x]
  Estimated Cycles:             264|313             (-15.6550%) [-1.18561x]

以下是比较算法的步骤

1. 运行第一个基准测试函数中的所有基准测试
2. 在第二个基准测试函数中运行第一个基准测试，如果第一个基准测试函数中存在具有相同id的基准测试，则比较它们
3. 在第二个基准测试函数中运行第二个基准测试...
4. ...
5. 在第三个基准函数中运行第一个基准测试，如果第一个基准函数中存在具有相同ID的基准测试，则比较它们。如果第二个基准函数中存在具有相同ID的基准测试，则比较它们。
6. 在第三个基准函数中运行第二个基准测试...
7. 依次类推...直到所有基准测试都相互比较

基准函数内基准测试的顺序和数量并不重要，因此没有必要在第二个、第三个等基准函数中严格镜像第一个基准函数的基准测试ID。

配置

可以配置一些 iai-callgrind 的行为。有关 LibraryBenchmarkConfig 的详细信息，请参阅 docs。在顶级使用 main! 宏

use iai_callgrind::{main, LibraryBenchmarkConfig};

main!(
    config = LibraryBenchmarkConfig::default();
    library_benchmark_groups = /* ... */
);

在组级别

use iai_callgrind::{library_benchmark_group, LibraryBenchmarkConfig};

library_benchmark_group!(
    name = some_name;
    config = LibraryBenchmarkConfig::default();
    benchmarks = /* ... */
);

在 library_benchmark 级别

use iai_callgrind::{library_benchmark, LibraryBenchmarkConfig};

#[library_benchmark(config = LibraryBenchmarkConfig::default())]
/* ... */

以及在 bench 级别

use iai_callgrind::{library_benchmark, LibraryBenchmarkConfig};

#[library_benchmark]
#[bench::some_id(args = (1, 2), config = LibraryBenchmarkConfig::default())]
/* ... */

在 bench 级别的配置会覆盖 library_benchmark 级别的配置。在 library_benchmark 级别的配置会覆盖组级别的配置，依此类推。请注意，如 envs 这样的配置值是累加的，并不会覆盖更高级别的配置值。

示例

有关一个完全文档化和可工作的基准测试，请参阅 test_lib_bench_groups 基准测试文件，并阅读 library documentation！

二进制基准测试

使用此方案来基准测试您crate的一个或多个二进制文件或系统上安装的任何二进制文件。设置二进制基准测试的API几乎与库基准测试等效。本节重点关注差异。有关基础知识，请参阅 Library Benchmarks。

重要默认行为

与库基准测试一样，在运行基准测试之前会清除基准测试二进制文件的环境变量。有关如何将环境变量传递给基准测试二进制文件的说明，请参阅 环境变量。

快速入门

假设crate的二进制文件名为 my-foo，并且这个二进制文件接受一个文件路径作为位置参数。此第一个示例展示了使用带有 #[binary_benchmark] 属性的高级API的基本用法

use iai_callgrind::{binary_benchmark, binary_benchmark_group, main};

#[binary_benchmark]
#[bench::some_id("foo.txt")]
fn bench_binary(path: &str) -> iai_callgrind::Command {
    iai_callgrind::Command::new(env!("CARGO_BIN_EXE_my-foo"))
        .arg(path)
        .build()
}

binary_benchmark_group!(
    name = my_group;
    benchmarks = bench_binary
);

main!(binary_benchmark_groups = my_group);

或使用低级API几乎相同

use iai_callgrind::{BinaryBenchmark, Bench, binary_benchmark_group, main};

binary_benchmark_group!(
    name = my_group;
    benchmarks = |group: &mut BinaryBenchmarkGroup| {
        group.binary_benchmark(BinaryBenchmark::new("bench_binary")
            .bench(Bench::new("some_id")
                .command(iai_callgrind::Command::new(env!("CARGO_BIN_EXE_my-foo"))
                    .arg("foo.txt")
                    .build()
                )
            )
        )
    }
);

main!(binary_benchmark_groups = my_group);

由于低级API已在 docs 中全面文档化，并且基本上反映了高级API，因此我们在此不深入探讨低级API的细节。

从库基准测试来看，包含 library 的名称更改为相同的名称，但将 library 替换为 binary，因此 #[library_benchmark] 属性的名称更改为 #[binary_benchmark]，library_benchmark_group! 更改为 binary_benchmark_group!，配置参数接受一个 BinaryBenchmarkConfig 而不是 LibraryBenchmarkConfig...

最重要的区别在于，被注解的函数#[binary_benchmark]始终需要返回一个iai_callgrind::Command。注意，这个函数构建了将要进行基准测试的命令，但不会执行它。因此，这个函数中的代码不会对实际基准测试的事件计数产生影响。

use iai_callgrind::binary_benchmark;
use std::path::PathBuf;

#[binary_benchmark]
#[bench::foo("foo.txt")]
#[bench::bar("bar.json")]
fn bench_binary(path: &str) -> iai_callgrind::Command {
    // We can put any code in this function which is needed to configure and
    // build the `Command`.
    let path = PathBuf::from(path);

    // Here, if the `path` ends with `.txt` we want to see
    // the `Stdout` output of the `Command` in the benchmark output. In all other 
    // cases, the `Stdout` of the `Command` is redirected to a `File` with the
    // same name as the input `path` but with the extension `out`.
    let stdout = if path.extension() == "txt" {
        iai_callgrind::Stdio::Inherit
    } else {
        iai_callgrind::Stdio::File(path.with_extension("out"))
    };
    iai_callgrind::Command::new(env!("CARGO_BIN_EXE_my-foo"))
        .stdout(stdout)
        .arg(path)
        .build()
}
// ... binary_benchmark_group! and main!

setup和teardown

由于我们可以在函数本身中放置任何构建Command的代码，因此setup和teardown在#[binary_benchmark]、#[bench]和#[benches]中的工作方式不同。

use iai_callgrind::binary_benchmark;

fn create_file() {
    std::fs::write("foo.txt", "some content").unwrap();
}

#[binary_benchmark]
#[bench::foo("foo.txt", setup = create_file())]
fn bench_binary(path: &str) -> iai_callgrind::Command {
    iai_callgrind::Command::new(env!("CARGO_BIN_EXE_my-foo"))
        .arg(path)
        .build()
}

setup，这里是指表达式create_file()，并不会立即被评估，并且setup的返回值也不会作为输入传递给function！相反，setup中的表达式将在基准测试的Command执行前被评估和执行。同样，teardown在Command执行后被执行。在这个例子中，setup始终创建相同的文件，并且是相当静态的。可以使用相同的参数来使用路径或文件指针到函数的setup（teardown）和函数。

use iai_callgrind::binary_benchmark;

fn create_file(path: &str) {
    std::fs::write(path, "some content").unwrap();
}

fn delete_file(path: &str) {
    std::fs::remove_file(path).unwrap();
}

#[binary_benchmark]
// Note the missing parentheses for `setup` of the function `create_file` which
// tells iai-callgrind to pass the `args` to the `setup` function AND the
// function `bench_binary`
#[bench::foo(args = ("foo.txt"), setup = create_file)]
// Same for `teardown`
#[bench::bar(args = ("bar.txt"), setup = create_file, teardown = delete_file)]
fn bench_binary(path: &str) -> iai_callgrind::Command {
    iai_callgrind::Command::new(env!("CARGO_BIN_EXE_my-foo"))
        .arg(path)
        .build()
}
// ... binary_benchmark_group! and main!

Sandbox

如上节所示，创建仅用于基准测试的文件的清理可能会变得很麻烦。出于这个目的以及许多其他原因，最好在一个临时目录中运行setup、Command本身和teardown。这个临时目录，即Sandbox，在基准测试结束后将被删除，无论基准测试是否成功。如果你只依赖于teardown，则后者并不保证，因为teardown仅在Command无错误返回时执行。

use iai_callgrind::{binary_benchmark, BinaryBenchmarkConfig, Sandbox};

fn create_file(path: &str) {
    std::fs::write(path, "some content").unwrap();
}

#[binary_benchmark]
#[bench::foo(
    args = ("foo.txt"),
    config = BinaryBenchmarkConfig::default().sandbox(Sandbox::new(true)),
    setup = create_file
)]
fn bench_binary(path: &str) -> iai_callgrind::Command {
    iai_callgrind::Command::new(env!("CARGO_BIN_EXE_my-foo"))
        .arg(path)
        .build()
}
// ... binary_benchmark_group! and main!

在这个例子中，作为setup的一部分，在Command执行之前，在Sandbox中执行了带有参数foo.txt的create_file函数。在相同的Sandbox中执行Command，因此由于setup的存在，文件foo.txt及其内容some content存在。在执行Command和可能的teardown之后，将完全删除Sandbox，删除在setup、Command执行和teardown期间创建的所有文件。

由于setup在沙箱中运行，您现在不能再那么容易地从项目的 workspace 复制 fixtures 到沙箱中。可以通过在Sandbox::fixtures中使用Sandbox来配置将fixtures复制到临时目录。

use iai_callgrind::{binary_benchmark, BinaryBenchmarkConfig, Sandbox};

#[binary_benchmark]
#[bench::foo(
    args = ("foo.txt"),
    config = BinaryBenchmarkConfig::default()
        .sandbox(Sandbox::new(true)
            .fixtures(["benches/foo.txt"])),
)]
fn bench_binary(path: &str) -> iai_callgrind::Command {
    iai_callgrind::Command::new(env!("CARGO_BIN_EXE_my-foo"))
        .arg(path)
        .build()
}
// ... binary_benchmark_group! and main!

上述操作会将位于benches目录中的foo.txt这个 fixtures 文件复制到沙箱根目录，并以foo.txt的形式存在。在Sandbox::fixtures中的相对路径相对于 workspace 根目录进行解析。在一个多 crate 的 workspace 中，这是包含顶级Cargo.toml文件的目录。在Sandbox::fixtures中的路径不仅限于文件，也可以是目录。

如果您有更复杂的需求，可以在setup和teardown中通过环境变量_WORKSPACE_ROOT访问 workspace 根目录。例如，假设有一个位于/home/the_project/foo_crate/benches/fixtures/foo.txt的 fixtures，其中the_project是 workspace 根目录，而foo_crate是一个包含my-foo可执行文件的 workspace 成员。如果命令期望创建一个bar.json文件，该文件在基准测试运行后需要进一步检查，我们可以将其复制到foo_crate中的临时目录tmp（可能存在或不存在）中。

use iai_callgrind::{binary_benchmark, BinaryBenchmarkConfig, Sandbox};
use std::path::PathBuf;

fn copy_fixture(path: &str) {
    let workspace_root = PathBuf::from(std::env::var_os("_WORKSPACE_ROOT").unwrap());
    std::fs::copy(
        workspace_root.join("foo_crate").join("benches").join("fixtures").join(path),
        path
    );
}

// This function will fail if `bar.json` does not exist, which is fine as this
// file is expected to be created by `my-foo`. So, if this file does not exist,
// an error will occur and the benchmark will fail. Although benchmarks are not
// expected to test the correctness of the application, the `teardown` can be
// used to check postconditions for a successful command run.
fn copy_back(path: &str) {
    let workspace_root = PathBuf::from(std::env::var_os("_WORKSPACE_ROOT").unwrap());
    let dest_dir = workspace_root.join("foo_crate").join("tmp");
    if !dest_dir.exists() {
        std::fs::create_dir(dest_dir).unwrap();
    }
    std::fs::copy(path, dest_dir.join(path));
}

#[binary_benchmark]
#[bench::foo(
    args = ("foo.txt"),
    config = BinaryBenchmarkConfig::default().sandbox(Sandbox::new(true)),
    setup = copy_fixture,
    teardown = copy_back("bar.json")
)]
fn bench_binary(path: &str) -> iai_callgrind::Command {
    iai_callgrind::Command::new(env!("CARGO_BIN_EXE_my-foo"))
        .arg(path)
        .build()
}

// ... binary_benchmark_group! and main!

命令的 stdin 和模拟管道输入

Command的Stdin的行为可以改变，几乎与std::process::Command的Stdin相同，唯一的区别是我们使用枚举iai_callgrind::Stdin和iai_callgrind::Stdio。这些枚举提供了Inherit（与std::process::Stdio::inherit等价）、Pipe（与std::process::Stdio::piped等价）等变体。还有一个File，它接受一个指向文件的PathBuf，该文件被iai-callgrind重定向为Command的Stdin。

此外，iai_callgrind::Stdin还提供了针对iai-callgrind的特定变体Stdin::Setup。

如果输入或Command的Stdin来自管道，应用程序可能会改变其行为。为了能够对这些情况进行基准测试，可以将setup的输出用作Command的Stdout或Stderr的输入。

use iai_callgrind::{binary_benchmark, Stdin, Pipe};

fn setup_pipe() {
    println!(
        "The output to `Stdout` here will be the input or `Stdin` of the `Command`"
    );
}

#[binary_benchmark]
#[bench::foo(setup = setup_pipe())]
fn bench_binary() -> iai_callgrind::Command {
    iai_callgrind::Command::new(env!("CARGO_BIN_EXE_my-foo"))
        .stdin(Stdin::Setup(Pipe::Stdout))
        .build()
}

// ... binary_benchmark_group! and main!

通常，先执行 setup，然后依次执行 Command 和 teardown，每个过程都会等待前一个过程成功退出（参见配置Command的退出码。如果 Command::stdin 变为 Stdin::Setup，则 setup 和 Command 并行执行，iai-callgrind 首先等待 Command 退出，然后等待 setup。在 setup 成功退出后，执行 teardown。

配置Command的退出码

通常，如果一个 Command 以非零退出码退出，则整个基准测试运行失败并停止。如果期望基准测试的 Command 的退出码与 0 不同，可以在 BinaryBenchmarkConfig::exit_with 或 Command::exit_with 中设置期望的退出码。

use iai_callgrind::{binary_benchmark, BinaryBenchmarkConfig, ExitWith};

#[binary_benchmark]
// Here, we set the expected exit code of `my-foo` to 2
#[bench::foo(
    config = BinaryBenchmarkConfig::default().exit_with(ExitWith::Code(2))
)]
// Here, we don't know the exact exit code but know it is different from 0 (=success)
#[bench::bar(
    config = BinaryBenchmarkConfig::default().exit_with(ExitWith::Failure)
)]
fn bench_binary() -> iai_callgrind::Command {
    iai_callgrind::Command::new(env!("CARGO_BIN_EXE_my-foo")).build()
}

// ... binary_benchmark_group! and main!

use iai_callgrind::{main, LibraryBenchmarkConfig, RegressionConfig, EventKind};
/* library benchmarks and groups */
main!(
    config = LibraryBenchmarkConfig::default()
        .regression(
            RegressionConfig::default()
                .limits([(EventKind::Ir, 5.0)])
        );
    library_benchmark_groups = some_group
);

use iai_callgrind::{
    library_benchmark, library_benchmark_group, main, LibraryBenchmarkConfig, Tool,
    ValgrindTool
};

#[library_benchmark]
fn some_func() {
    println!("Hello, World!");
}

library_benchmark_group!(name = some_group; benchmarks = some_func);

main!(
    config = LibraryBenchmarkConfig::default()
                .tool(Tool::new(ValgrindTool::DHAT));
    library_benchmark_groups = some_group
);

use iai_callgrind::{Tool, ValgrindTool};

Tool::new(ValgrindTool::Memcheck).args(["--error-exitcode=0"]);

[dev-dependencies]
iai-callgrind = { version = "0.13.0", features = ["client_requests"] }

[dependencies]
iai-callgrind = { version = "0.13.0", default-features = false, features = [
    "client_requests_defs"
] }

[dev-dependencies]
iai-callgrind = { version = "0.13.0", features = ["client_requests"] }

use iai_callgrind::client_requests;

fn main() {
    // Start callgrind event counting if not already started earlier
    client_requests::callgrind::start_instrumentation();

    // do something important

    // Toggle callgrind event counting off
    client_requests::callgrind::toggle_collect();
}

git checkout main
cargo bench --bench <benchmark> -- --save-baseline=main
git checkout feature
# ... HACK ... HACK
cargo bench --bench <benchmark> -- --baseline main

use iai_callgrind::{main, library_benchmark_group, library_benchmark};
use my_lib::some_function;

#[library_benchmark]
#[bench::short(10)]
fn bench_function(value: u64) -> u64 {
    some_function(value)
}

library_benchmark_group!(
    name = bench_group;
    benchmarks = bench_function
);

main!(library_benchmark_groups = bench_group);

use iai_callgrind::{main, library_benchmark_group, library_benchmark};

fn my_teardown(value: u64) {
    eprintln!("Error output during teardown: {value}");
}

fn to_be_benchmarked(value: u64) -> u64 {
    println!("Output to stdout: {value}");
    value + 10
}

#[library_benchmark]
#[bench::some_id(args = (10), teardown = my_teardown)]
fn my_bench(value: u64) -> u64 {
    to_be_benchmarked(value)
}

library_benchmark_group!(
    name = my_bench_group;
    benchmarks = my_bench
);

main!(library_benchmark_groups = my_bench_group);

my_benchmark::my_bench_group::my_bench some_id:10
Output to stdout: 10
Error output during teardown: 20
- end of stdout/stderr
  Instructions:              331082|N/A             (*********)
  L1 Hits:                   442452|N/A             (*********)
  L2 Hits:                      720|N/A             (*********)
  RAM Hits:                    3926|N/A             (*********)
  Total read+write:          447098|N/A             (*********)
  Estimated Cycles:          583462|N/A             (*********)

$ cd iai-callgrind
$ cargo bench --bench test_lib_bench_readme_example_fibonacci
test_lib_bench_readme_example_fibonacci::bench_fibonacci_group::bench_fibonacci short:10
  Instructions:                1733|N/A             (*********)
  L1 Hits:                     2359|N/A             (*********)
  L2 Hits:                        0|N/A             (*********)
  RAM Hits:                       2|N/A             (*********)
  Total read+write:            2361|N/A             (*********)
  Estimated Cycles:            2429|N/A             (*********)
test_lib_bench_readme_example_fibonacci::bench_fibonacci_group::bench_fibonacci long:30
  Instructions:            26214733|N/A             (*********)
  L1 Hits:                 35638617|N/A             (*********)
  L2 Hits:                        0|N/A             (*********)
  RAM Hits:                       4|N/A             (*********)
  Total read+write:        35638621|N/A             (*********)
  Estimated Cycles:        35638757|N/A             (*********)

test_lib_bench_readme_example_fibonacci::bench_fibonacci_group::bench_fibonacci short:10
  Instructions:                1733|N/A             (*********)
  L1 Hits:                     2359|N/A             (*********)
  L2 Hits:                        0|N/A             (*********)
  RAM Hits:                       2|N/A             (*********)
  Total read+write:            2361|N/A             (*********)
  Estimated Cycles:            2429|N/A             (*********)

[lib]
bench = false

[[bin]]
name = "my-binary"
path = "src/bin/my-binary.rs"
bench = false