Iai-Callgrind

高精度且一致的Rust基准测试框架/工具

Iai-Callgrind是一个基准测试框架/工具，它使用Valgrind的Callgrind和其他Valgrind工具，如DHAT、Massif等，包括Cachegrind，以提供对Rust代码极其准确和一致的测量，使其非常适合在像CI这样的环境中运行。Iai-Callgrind已集成到Bencher中。

Iai-Callgrind具有以下特点：

• 精确：高精度的指令计数和许多其他指标的测量，使您能够可靠地检测代码的非常小的优化和回归。
• 一致：Iai-Callgrind即使在虚拟化的CI环境中也能进行准确的测量，并使它们在不同系统之间具有可比性，完全消除了环境的噪声。
• 快速：每个基准测试只运行一次，这通常比测量执行时间和挂钟时间的基准测试快得多。测量挂钟时间的基准测试必须运行多次以提高其准确性、检测异常值、过滤噪声等。
• 可视化：Iai-Callgrind生成基准测试代码的Callgrind（DHAT等）配置文件，并可以配置为从Callgrind指标创建类似火焰图的图表。通常，所有与Valgrind兼容的工具，如callgrind_annotate、kcachegrind或dh_view.html等，都完全支持详细分析结果。
• 简单：设置基准测试的API易于使用，使您能够快速创建简洁明了的基准测试。更多地关注分析和代码，而不是框架。

设计理念和目标

Iai-Callgrind基准测试设计为可通过cargo bench运行。基准测试文件扩展为一个基准测试工具，该工具替换了Rust的本地基准测试工具。Iai-Callgrind是一个分析框架，可以快速可靠地检测性能回归和优化，即使在嘈杂的环境中，其精度也是基于挂钟时间的基准测试无法实现的。同时，我们希望抽象出复杂的部分和重复性任务，并提供易于使用和直观的API。Iai-Callgrind试图不干扰您的工作，并应用合理的默认设置，以便您可以更多地关注分析和代码！

进展程度

Iai-Callgrind处于成熟的开发阶段，并且已经在使用中。尽管如此，您可能会在次要版本更新之间经历重大变化。随着0.14.0版本的发布，几乎所有的Callgrind功能都已实现，包括多线程和多进程应用程序的基准测试。从0.15.0版本开始，可以使用Cachegrind代替或补充Callgrind。从0.16.0版本开始，使用DHAT进行堆使用分析已完全集成。使用Massif进行分析是可能的，但在终端输出中不显示有用的指标，并且可以进一步改进。为多进程/多线程基准测试创建callgrind火焰图被认为处于实验状态。

何时不使用Iai-Callgrind

尽管Iai-Callgrind在许多项目中都有用，但在某些情况下，Iai-Callgrind并不适合。

• 如果您需要挂钟时间，Iai-Callgrind对您没有太大帮助。CPU周期的估计仅与挂钟时间相关，但不能替代挂钟时间。周期估计主要设计为用于比较的相对指标。
• Iai-Callgrind无法在Windows和Valgrind不支持的平台上运行。

贡献

感谢您帮助改进这个项目！关于如何为Iai-Callgrind做出贡献的指南可以在CONTRIBUTING.md文件中找到。

您有一个新功能的想法，缺少某个功能，或者发现了一个错误？

请不要犹豫，提交一个问题。

除非您明确声明，否则您为包含在工作中的任何贡献都应按照许可证中的规定进行双重许可，无需任何附加条款或条件。

致谢

Iai-Callgrind是从Iai分叉出来的，原始想法来自Brook Heisler。

Iai-Callgrind由Valgrind提供支持。

许可证

Iai-Callgrind像Iai一样，根据Apache 2.0许可证和MIT许可证双重许可，您可以选择。

根据Valgrind的文档：

Valgrind头文件与大部分代码不同，采用BSD风格的许可证，因此您可以包含它们而无需担心许可证不兼容。

我们在使用原始头文件的地方包含了原始许可证。

示例代码：

// 添加iai-callgrind到Cargo.toml的依赖项
// [dev-dependencies]
// iai-callgrind = "0.16.1"

// 在benches目录下的基准测试文件，例如benches/my_benchmark.rs

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

// 定义一个简单的函数进行基准测试
fn fibonacci(n: u64) -> u64 {
    match n {
        0 => 1,
        1 => 1,
        n => fibonacci(n-1) + fibonacci(n-2),
    }
}

// 使用library_benchmark属性标记基准测试函数
#[library_benchmark]
fn bench_fibonacci() -> u64 {
    // 调用要测试的函数
    fibonacci(20)
}

// 定义基准测试组
library_benchmark_group!(
    name = bench_group;
    benchmarks = bench_fibonacci
);

// 主函数，运行基准测试
main!(library_benchmark_groups = bench_group);

完整示例：

// 添加iai-callgrind到Cargo.toml的依赖项
// [dev-dependencies]
// iai-callgrind = "0.16.1"

// 在benches目录下的基准测试文件，例如benches/my_benchmark.rs

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

// 定义一个简单的函数进行基准测试
fn fibonacci(n: u64) -> u64 {
    match n {
        0 => 1,
        1 => 1,
        n => fibonacci(n-1) + fibonacci(n-2),
    }
}

// 使用library_benchmark属性标记基准测试函数
#[library_benchmark]
fn bench_fibonacci() -> u64 {
    // 调用要测试的函数
    fibonacci(20)
}

// 可以定义多个基准测试函数
#[library_benchmark]
fn bench_fibonacci_small() -> u64 {
    fibonacci(10)
}

#[library_benchmark]
fn bench_fibonacci_large() -> u64 {
    fibonacci(30)
}

// 定义基准测试组，包含多个基准测试
library_benchmark_group!(
    name = fibonacci_benchmarks;
    benchmarks = bench_fibonacci, bench_fibonacci_small, bench_fibonacci_large
);

// 主函数，运行基准测试组
main!(library_benchmark_groups = fibonacci_benchmarks);

运行基准测试：

cargo bench

这将使用iai-callgrind运行基准测试，并生成详细的性能分析报告，包括指令计数、缓存命中率等指标。

完整示例demo：

// Cargo.toml配置
// [dev-dependencies]
// iai-callgrind = "0.16.1"

// benches/my_benchmark.rs
use iai_callgrind::{main, library_benchmark, library_benchmark_group, LibraryBenchmarkConfig};

// 基准测试的目标函数
fn process_data(input: &[i32]) -> Vec<i32> {
    input.iter()
        .map(|x| x * 2)
        .filter(|x| x % 3 == 0)
        .collect()
}

// 使用library_benchmark属性标记基准测试函数
#[library_benchmark]
fn bench_small_data() -> Vec<i32> {
    let data = vec![1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
    process_data(&data)
}

#[library_benchmark]
fn bench_medium_data() -> Vec<i32> {
    let data: Vec<i32> = (1..=100).collect();
    process_data(&data)
}

#[library_benchmark]
fn bench_large_data() -> Vec<i32> {
    let data: Vec<i32> = (1..=1000).collect();
    process_data(&data)
}

// 配置基准测试参数
#[library_benchmark]
#[config(
    LibraryBenchmarkConfig::default()
        .raw_callgrind_args(["--simulate-cache=yes"])
)]
fn bench_with_cache_simulation() -> Vec<i32> {
    let data: Vec<i32> = (1..=500).collect();
    process_data(&data)
}

// 定义基准测试组
library_benchmark_group!(
    name = data_processing_benchmarks;
    benchmarks = 
        bench_small_data, 
        bench_medium_data, 
        bench_large_data,
        bench_with_cache_simulation
);

// 主函数，运行所有基准测试组
main!(library_benchmark_groups = data_processing_benchmarks);