oxigeo_bench/lib.rs
1//! OxiGeo Benchmarking and Profiling Suite
2//!
3//! `oxigeo-bench` provides comprehensive performance profiling and benchmarking
4//! capabilities for the OxiGeo geospatial library ecosystem.
5//!
6//! # Features
7//!
8//! - **CPU Profiling**: Profile CPU usage with flamegraph generation
9//! - **Memory Profiling**: Track memory usage and detect leaks
10//! - **Benchmark Scenarios**: Predefined scenarios for common operations
11//! - **Performance Comparison**: Compare performance across implementations
12//! - **Regression Detection**: Detect performance regressions against baselines
13//! - **Report Generation**: Generate HTML, JSON, CSV, and Markdown reports
14//!
15//! # Example
16//!
17//! ```rust,no_run
18//! use oxigeo_bench::scenarios::{ScenarioBuilder, ScenarioRunner};
19//! use oxigeo_bench::report::{BenchmarkReport, ReportFormat};
20//!
21//! // Create a custom benchmark scenario
22//! let scenario = ScenarioBuilder::new("my_benchmark")
23//! .description("Test raster processing")
24//! .execute(|| {
25//! // Your benchmark code here
26//! Ok(())
27//! })
28//! .build();
29//!
30//! // Run the scenario
31//! let mut runner = ScenarioRunner::new();
32//! runner.add_scenario(scenario);
33//! runner.run_all().expect("Failed to run benchmarks");
34//!
35//! // Generate a report
36//! let mut report = BenchmarkReport::new("My Benchmark Report");
37//! report.add_scenario_results(runner.results().to_vec());
38//! report.generate("report.html", ReportFormat::Html)
39//! .expect("Failed to generate report");
40//! ```
41//!
42//! # Scenario Modules
43//!
44//! - `scenarios::raster`: Raster operation benchmarks (requires `raster` feature)
45//! - `scenarios::vector`: Vector operation benchmarks (requires `vector` feature)
46//! - [`scenarios::io`]: I/O performance benchmarks
47//! - `scenarios::cloud`: Cloud storage benchmarks (requires `cloud` feature)
48//! - `scenarios::ml`: ML inference benchmarks (requires `ml` feature)
49//!
50//! # Profiling
51//!
52//! The `profiler` module provides memory-usage profiling utilities
53//! ([`profiler::MemoryProfiler`], [`profiler::SystemMonitor`]) unconditionally.
54//! CPU/flamegraph profiling (`profiler::CpuProfiler`, `profiler::profile_cpu`)
55//! additionally requires the non-default `profiling` feature, since it
56//! pulls in `pprof` -> `backtrace` -> `miniz_oxide` (kept out of the default
57//! build graph by the Pure Rust Policy):
58//!
59//! ```rust,ignore
60//! // Requires: cargo build --features profiling
61//! use oxigeo_bench::profiler::{profile_cpu, CpuProfilerConfig};
62//!
63//! let config = CpuProfilerConfig {
64//! frequency: 100,
65//! generate_flamegraph: true,
66//! ..Default::default()
67//! };
68//!
69//! let (result, report) = profile_cpu(|| {
70//! // Code to profile
71//! 42
72//! }, config).expect("Profiling failed");
73//!
74//! println!("Profiling duration: {:?}", report.duration);
75//! ```
76
77#![deny(clippy::unwrap_used)]
78#![deny(clippy::panic)]
79#![warn(missing_docs)]
80#![warn(clippy::expect_used)]
81#![allow(unexpected_cfgs)]
82
83// Re-export commonly used types
84pub use error::{BenchError, Result};
85
86// Core modules
87pub mod comparison;
88pub mod error;
89#[cfg(feature = "ml")]
90pub mod ml_fixtures;
91pub mod profiler;
92pub mod regression;
93pub mod report;
94pub mod scenarios;
95
96// Version information
97/// The version of this crate.
98pub const VERSION: &str = env!("CARGO_PKG_VERSION");
99
100/// The name of this crate.
101pub const CRATE_NAME: &str = env!("CARGO_PKG_NAME");
102
103// Prelude module for convenient imports
104pub mod prelude {
105 //! Prelude module with commonly used types and traits.
106
107 pub use crate::comparison::{Comparison, ComparisonSuite, Implementation};
108 pub use crate::error::{BenchError, Result};
109 #[cfg(feature = "profiling")]
110 pub use crate::profiler::{CpuProfiler, CpuProfilerConfig, profile_cpu};
111 pub use crate::profiler::{
112 MemoryProfiler, MemoryProfilerConfig, SystemMonitor, profile_memory,
113 };
114 pub use crate::regression::{
115 Baseline, BaselineStore, RegressionConfig, RegressionDetector, RegressionReport,
116 RegressionResult, RegressionSeverity,
117 };
118 pub use crate::report::{BenchmarkReport, ReportBuilder, ReportFormat};
119 pub use crate::scenarios::{
120 BenchmarkScenario, CustomScenario, ScenarioBuilder, ScenarioResult, ScenarioRunner,
121 };
122}
123
124#[cfg(test)]
125mod tests {
126 use super::*;
127
128 #[test]
129 fn test_version() {
130 assert!(!VERSION.is_empty());
131 assert_eq!(CRATE_NAME, "oxigeo-bench");
132 }
133}