Crate divan

Divan

Comfy benchmarking for Rust projects, brought to you by Nikolai Vazquez.

Getting Started

1. Add the following to your project’s Cargo.toml:

   [dev-dependencies]
   divan = "0.1.0"
   
   [[bench]]
   name = "example"
   harness = false
   

2. Create a benchmarks file at benches/example.rs^[1] with your benchmarking code:

   fn main() {
       // Run registered benchmarks.
       divan::main();
   }
   
   // Define a `fibonacci` function and register it for benchmarking.
   #[divan::bench]
   fn fibonacci() -> u64 {
       fn compute(n: u64) -> u64 {
           if n <= 1 {
               1
           } else {
               compute(n - 2) + compute(n - 1)
           }
       }
   
       compute(divan::black_box(10))
   }

3. Run your benchmarks with cargo bench:

   example       fastest  │ slowest │ median   │ mean     │ samples │ iters
   ╰─ f​ibonacci  196.1 ns │ 217 ns  │ 197.5 ns │ 198.1 ns │ 100     │ 3200
   

See #[divan::bench] for info on benchmark function registration.

Examples

Practical example benchmarks can be found in the examples/benches directory. These can be benchmarked locally by running:

git clone https://github.com/nvzqz/divan.git
cd divan

cargo bench -q -p examples --all-features

More thorough usage examples can be found in the #[divan::bench] documentation.

License

Like the Rust project, this library may be used under either the MIT License or Apache License (Version 2.0).

Footnotes

1. Within your crate directory, i.e. $CARGO_MANIFEST_DIR

Modules

• counter
  Count values processed in each iteration to measure throughput.

Structs

• Bencher
  Enables contextual benchmarking in #[divan::bench].
• Divan
  The benchmark runner.

Functions

• black_box
  An identity function that hints to the compiler to be maximally pessimistic about what black_box could do.
• main
  Runs all registered benchmarks.

Attribute Macros

• bench
  Registers a benchmarking function.
• bench_group
  Registers a benchmarking group.