# mobench-macros
Procedural macros for the [mobench](https://crates.io/crates/mobench) mobile benchmarking framework.
This crate provides the `#[benchmark]` attribute macro that automatically registers functions for mobile benchmarking. It uses compile-time registration via the `inventory` crate to build a registry of benchmark functions.
In `mobench 0.1.22`, benchmarks annotated with these macros are discovered through the CLI's config-first resolver, so non-legacy crate layouts work with `mobench.toml`, `--project-root`, and `--crate-path`.
## Features
- **`#[benchmark]` attribute**: Mark functions as benchmarks
- **Automatic registration**: No manual registry maintenance required
- **Type safety**: Compile-time validation of benchmark functions
- **Zero runtime overhead**: Registration happens at compile time
## Usage
Add this to your `Cargo.toml`:
```toml
[dependencies]
mobench-macros = "0.1.22"
mobench-sdk = "0.1.22" # For the runtime
```
### Basic Example
```rust
use mobench_macros::benchmark;
#[benchmark]
fn fibonacci_benchmark() {
let result = fibonacci(30);
std::hint::black_box(result);
}
#[benchmark]
fn sorting_benchmark() {
let mut data = vec![5, 2, 8, 1, 9];
data.sort();
std::hint::black_box(data);
}
fn fibonacci(n: u32) -> u64 {
match n {
0 => 0,
1 => 1,
_ => fibonacci(n - 1) + fibonacci(n - 2),
}
}
```
### With mobench-sdk
The macros work seamlessly with mobench-sdk:
```rust
use mobench_macros::benchmark;
use mobench_sdk::{run_benchmark, BenchSpec};
#[benchmark]
fn my_expensive_operation() {
// Your benchmark code
}
fn main() -> Result<(), Box<dyn std::error::Error>> {
// Run the benchmark
let spec = BenchSpec::new("my_expensive_operation", 100, 10)?;
let report = run_benchmark(spec)?;
println!("Mean: {} ns", report.mean_ns());
Ok(())
}
```
## How It Works
The `#[benchmark]` macro:
1. **Preserves your function**: The original function remains unchanged
2. **Generates registration code**: Creates an `inventory::submit!` call
3. **Wraps in closure**: Converts your function into a callable closure
4. **Registers at compile time**: Adds to the global benchmark registry
### Macro Expansion
When you write:
```rust
#[benchmark]
fn my_benchmark() {
expensive_operation();
}
```
The macro expands to something like:
```rust
fn my_benchmark() {
expensive_operation();
}
inventory::submit! {
BenchFunction {
name: "my_benchmark",
runner: |spec| {
run_closure(spec, || {
my_benchmark();
Ok(())
})
}
}
}
```
## Setup and Teardown
For benchmarks that need expensive setup that shouldn't be measured:
```rust
use mobench_macros::benchmark;
fn setup_data() -> Vec<u8> {
vec![0u8; 1_000_000] // Not measured
}
#[benchmark(setup = setup_data)]
fn hash_benchmark(data: &Vec<u8>) {
std::hint::black_box(compute_hash(data)); // Only this is measured
}
```
### Per-Iteration Setup
For benchmarks that mutate their input (e.g., sorting):
```rust
fn generate_random_vec() -> Vec<i32> {
(0..1000).collect()
}
#[benchmark(setup = generate_random_vec, per_iteration)]
fn sort_benchmark(data: Vec<i32>) {
let mut data = data;
data.sort();
std::hint::black_box(data);
}
```
### Setup and Teardown
```rust
fn setup_db() -> Database { Database::connect("test.db") }
fn cleanup_db(db: Database) { db.close(); }
#[benchmark(setup = setup_db, teardown = cleanup_db)]
fn db_query(db: &Database) {
db.query("SELECT * FROM users");
}
```
## Requirements
- Functions must be regular functions (not async)
- Without setup: no parameters allowed
- With setup: exactly one parameter (reference to setup result, or owned for per_iteration)
- Functions should use `std::hint::black_box()` to prevent optimization of results
## Best Practices
### Prevent Compiler Optimization
Always use `black_box` for benchmark results:
```rust
use mobench_macros::benchmark;
#[benchmark]
fn good_benchmark() {
let result = expensive_computation();
std::hint::black_box(result); // ✓ Prevents optimization
}
#[benchmark]
fn bad_benchmark() {
let result = expensive_computation(); // ✗ May be optimized away
}
```
### Benchmark Naming
Use descriptive names that indicate what's being measured:
```rust
#[benchmark]
fn hash_1kb_data() { /* ... */ }
#[benchmark]
fn parse_json_small() { /* ... */ }
#[benchmark]
fn encrypt_aes_256() { /* ... */ }
```
### Isolate Benchmarks
Keep benchmarks focused on one operation:
```rust
// Good: Measures one thing
#[benchmark]
fn sha256_hash() {
let hash = sha256(&DATA);
std::hint::black_box(hash);
}
// Bad: Measures multiple things
#[benchmark]
fn hash_and_encode() {
let hash = sha256(&DATA);
let encoded = base64_encode(hash);
std::hint::black_box(encoded);
}
```
## Part of mobench
This crate is part of the mobench ecosystem for mobile benchmarking:
- **[mobench](https://crates.io/crates/mobench)** - CLI tool for running benchmarks
- **[mobench-sdk](https://crates.io/crates/mobench-sdk)** - Core SDK with timing harness, build automation, and codegen
- **[mobench-macros](https://crates.io/crates/mobench-macros)** - This crate (proc macros)
## See Also
- [mobench-sdk](https://crates.io/crates/mobench-sdk) for the complete SDK
- [mobench](https://crates.io/crates/mobench) for the CLI tool
- [inventory](https://crates.io/crates/inventory) for the registration mechanism
## License
Licensed under the MIT License. See [LICENSE.md](../../LICENSE.md) for details.
Copyright (c) 2026 World Foundation