fluxbench/
lib.rs

1#![warn(missing_docs)]
2//! # FluxBench
3//!
4//! Benchmarking framework for Rust with crash isolation, statistical rigor, and CI integration.
5//!
6//! FluxBench provides a next-generation benchmarking platform:
7//! - **Process Isolation**: Crash-resilient "Fail-Late" architecture; panicking benchmarks don't crash the suite
8//! - **Zero-Copy IPC**: Efficient supervisor-worker communication using rkyv serialization
9//! - **Statistical Rigor**: Bootstrap resampling with BCa (bias-corrected and accelerated) confidence intervals
10//! - **CI Integration**: Severity levels (critical/warning/info), GitHub Actions summaries, baseline comparison
11//! - **Algebraic Verification**: Performance assertions directly in code with mathematical expressions
12//! - **Synthetic Metrics**: Compute derived metrics from benchmark results
13//! - **Multi-Way Comparisons**: Generate comparison tables and series charts
14//! - **Allocation Tracking**: `TrackingAllocator` measures heap usage per iteration
15//! - **High-Precision Timing**: RDTSC cycle counting on x86_64 with Instant fallback
16//!
17//! ## Quick Start
18//!
19//! ```ignore
20//! use fluxbench::prelude::*;
21//!
22//! #[flux::bench]
23//! fn my_benchmark(b: &mut Bencher) {
24//!     b.iter(|| {
25//!         // Code to benchmark
26//!         expensive_operation()
27//!     });
28//! }
29//! ```
30//!
31//! ## Async Benchmarks
32//!
33//! ```ignore
34//! #[flux::bench(runtime = "multi_thread", worker_threads = 4)]
35//! async fn async_benchmark(b: &mut Bencher) {
36//!     b.iter(|| async {
37//!         tokio::time::sleep(Duration::from_millis(1)).await;
38//!     });
39//! }
40//! ```
41//!
42//! ## Performance Assertions
43//!
44//! ```ignore
45//! #[flux::verify(expr = "(raw - overhead) < 50000000", severity = "critical")]
46//! struct NetTimeCheck;
47//! ```
48
49// Re-export core types
50pub use fluxbench_core::{
51    Bencher, BenchmarkDef, BenchmarkResult, ChartDef, ChartType, CompareDef, GroupDef,
52    IterationMode, ReportDef, Severity, TrackingAllocator, current_allocation,
53    reset_allocation_counter,
54};
55
56// Re-export macros
57pub use fluxbench_macros::{bench, compare, group, report, synthetic, verify};
58
59// Re-export logic types
60pub use fluxbench_logic::{
61    MetricContext, SyntheticDef, Verification, VerificationResult, VerificationStatus, VerifyDef,
62};
63
64// Re-export stats
65pub use fluxbench_stats::{
66    BootstrapConfig, BootstrapResult, SummaryStatistics, compute_bootstrap, compute_summary,
67};
68
69/// Internal re-exports for macro use
70#[doc(hidden)]
71pub mod internal {
72    pub use inventory;
73    pub use tokio;
74}
75
76/// Prelude for convenient imports
77pub mod prelude {
78    pub use crate::{
79        Bencher, CompareDef, GroupDef, ReportDef, Severity, bench, compare, group, report,
80        synthetic, verify,
81    };
82}
83
84/// Attribute namespace for flux macros
85pub mod flux {
86    pub use fluxbench_macros::{bench, compare, group, report, synthetic, verify};
87}
88
89/// Run the FluxBench CLI harness.
90///
91/// Call this from your benchmark binary's `main()`:
92/// ```ignore
93/// fn main() {
94///     fluxbench::run().unwrap();
95/// }
96/// ```
97pub use fluxbench_cli::run;
fluxbench/lib.rs

fluxbench/
lib.rs
