Crate brunch

source · []
Expand description

Brunch

Brunch is a very simple Rust micro-benchmark runner inspired by easybench. It has roughly a million times fewer dependencies than criterion, does not require nightly, and maintains a “last run” state so can show relative changes benchmark-to-benchmark. The formatting is also quite pretty.

As with all Rust benchmarking, there are a lot of caveats, and results might be artificially fast or slow. For best resuilts, build optimized, avoid heavy setup contexts, and test different bench setups to find the most “honest” representation.

In theory, this library can reach pico-second scales (it clocks increasingly large batches and divides accordingly), but background noise and setup overhead will likely prevent times getting quite as low as they might “actually” be. It can go as long as milliseconds, but might require increased time limits to reach sufficient samples in such cases.

Work in Progress

This crate is still under heavy development. It is subject to going to change, so you probably don’t want to rely on it in production yet. But that said, feel free to poke around, steal code, find inspiration, etc.

Usage

Setup is currently simple if primitive, requiring you drop a call to the benches macro in the benchmark file. It will generate a main() method, run the supplied benchmarks, and give you the results.

An example bench file would look something like:

use brunch::Bench;
use dactyl::NiceU8;
use std::time::Duration;

brunch::benches!(
    Bench::new("dactyl::NiceU8", "from(0)")
        .timed(Duration::from_secs(1))
        .with(|| NiceU8::from(0_u8)),

    Bench::new("dactyl::NiceU8", "from(18)")
        .timed(Duration::from_secs(1))
        .with(|| NiceU8::from(18_u8)),

    Bench::new("dactyl::NiceU8", "from(101)")
        .timed(Duration::from_secs(1))
        .with(|| NiceU8::from(101_u8)),

    Bench::new("dactyl::NiceU8", "from(u8::MAX)")
        .timed(Duration::from_secs(1))
        .with(|| NiceU8::from(u8::MAX))
);

The Bench struct represents a benchmark. It takes two label arguments intended to represent a shared base (for the included benchmarks) and the unique bit, usually a method/value.

By default, each benchmark will run for approximately three seconds. This can be changed using the chained Bench::timed method as shown above.

There are currently three styles of callback:

MethodSignatureDescription
withFnMut() -> OExecute a self-contained callback.
with_setupFnMut(I) -> OExecute a callback seeded with a (cloneable) value.
with_setup_refFnMut(&I) -> OExecute a callback seeded with a referenced value.

Macros

Helper: Benchmarks

Structs

Benchmark.

Enums

Obligatory Error Enum.