Crate fluxbench 

FluxBench

Benchmarking framework for Rust with crash isolation, statistical rigor, and CI integration.

FluxBench provides a next-generation benchmarking platform:

• Process Isolation: Crash-resilient “Fail-Late” architecture; panicking benchmarks don’t crash the suite
• Binary IPC: Supervisor-worker messages use length-prefixed rkyv frames
• Statistical Rigor: Bootstrap resampling with BCa (bias-corrected and accelerated) confidence intervals
• CI Integration: Severity levels (critical/warning/info), GitHub Actions summaries, baseline comparison
• Algebraic Verification: Performance assertions directly in code with mathematical expressions
• Synthetic Metrics: Compute derived metrics from benchmark results
• Multi-Way Comparisons: Generate comparison tables and series charts
• Allocation Tracking: TrackingAllocator measures heap usage per iteration
• Timing: Instant per timed region with timer overhead subtracted. Cycle counts use RDTSCP (x86_64) or CNTVCT_EL0 (aarch64), else 0

Quick Start

use fluxbench::prelude::*;

#[flux::bench]
fn my_benchmark(b: &mut Bencher) {
    b.iter(|| {
        // Code to benchmark
        expensive_operation()
    });
}

Setup and Batching

iter_batched builds inputs untimed and hands each one to the routine by value. iter_batched_ref hands a &mut input instead. BatchSize sets the inputs per timed batch.

#[flux::bench]
fn sort_fresh(b: &mut Bencher) {
    b.iter_batched(
        || (0..1_000u32).rev().collect::<Vec<_>>(),
        |mut v| { v.sort(); v },
        BatchSize::SmallInput,
    );
}

#[flux::bench]
fn clear_in_place(b: &mut Bencher) {
    b.iter_batched_ref(|| vec![0u8; 4096], |v| v.fill(1), BatchSize::LargeInput);
}

iter_custom lets the body time iters calls itself:

#[flux::bench]
fn self_timed(b: &mut Bencher) {
    b.iter_custom(|iters| {
        let start = std::time::Instant::now();
        for _ in 0..iters {
            std::hint::black_box(2 + 2);
        }
        start.elapsed()
    });
}

Throughput

Set the work per call. Reports show bytes per second (binary units) or elements per second.

#[flux::bench(throughput_bytes = 4096)]
fn checksum_4k(b: &mut Bencher) {
    let data = vec![1u8; 4096];
    b.iter(|| data.iter().map(|&x| x as u64).sum::<u64>());
}

#[flux::bench]
fn parse_lines(b: &mut Bencher) {
    let lines: Vec<String> = (0..100).map(|i| i.to_string()).collect();
    b.throughput(Throughput::Elements(lines.len() as u64));
    b.iter(|| lines.iter().filter_map(|l| l.parse::<u32>().ok()).sum::<u32>());
}

Group Config

A group sets run config for its benchmarks and child groups. A #[flux::bench] attribute beats it. CLI flags and flux.toml lose to it.

#[flux::group(id = "io", sample_count = 30, measurement = "2s", warmup = "500ms")]
struct Io;

Async Benchmarks

The async feature (default) enables them. iter_async times creating and awaiting each future. The runtime builds once per benchmark. current_thread (the default) and multi_thread both work.

#[flux::bench(runtime = "multi_thread", worker_threads = 4)]
async fn async_benchmark(b: &mut Bencher) {
    b.iter_async(|| async {
        tokio::time::sleep(Duration::from_millis(1)).await;
    });
}

Performance Assertions

#[flux::verify(expr = "(raw - overhead) < 50000000", severity = "critical")]
struct NetTimeCheck;

Modules

flux

Attribute namespace for flux macros

prelude

Prelude for convenient imports

Structs

Bencher

The Bencher provides iteration control for benchmarks.

BenchmarkDef

Benchmark definition registered via #[flux::bench]

BenchmarkResult

Result of a single benchmark run

BootstrapConfig

Bootstrap configuration

BootstrapResult

Result of bootstrap analysis

ChartDef

Chart definition registered via #[flux::chart].

CompareDef

Comparison group - groups multiple benchmarks for side-by-side comparison

GroupConfig

Run config a #[flux::group] sets for every benchmark in it and in its child groups.

GroupDef

Group definition registered via #[flux::group].

MeasureConfig

Config for one benchmark measurement.

MetricContext

Context holding benchmark metrics for expression evaluation

ReportDef

Report definition registered via #[flux::report].

SummaryStatistics

Comprehensive summary statistics

SyntheticDef

Definition of a synthetic metric registered via #[flux::synthetic]

TrackingAllocator

Tracking allocator that wraps the system allocator

Verification

Verification definition

VerificationResult

Result of a verification check

VerifyDef

Definition of a verification rule registered via #[flux::verify]

Enums

BatchSize

Inputs per timed batch for iter_batched and iter_batched_ref.

ChartType

Chart kind for #[flux::chart]

IterationMode

Mode of iteration for the benchmark

MeasureError

Error from one benchmark measurement.

Severity

Severity levels for CI integration

Throughput

Work one routine call processes.

VerificationStatus

Verification execution status with explicit states for all outcomes.

Functions

compute_bootstrap

Compute bootstrap confidence interval for the mean

compute_summary

Compute summary statistics from the raw samples.

current_allocation

Get current allocation statistics

reset_allocation_counter

Reset allocation counters (call before each iteration)

run

Run the FluxBench CLI harness.

Attribute Macros

bench

Register a benchmark function

chart

Add an SVG chart of one metric per benchmark to the HTML report

compare

Define a comparison group for multiple benchmarks

group

Describe a benchmark group

report

Set the HTML report title, description, and chart grid

synthetic

Define a synthetic (computed) metric

verify

Define a performance verification