alloc_tracker 0.7.0

Memory allocation tracking utilities for benchmarks and performance analysis
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73

//! Example that demonstrates the `iter_custom` pattern shown in the README.md file.
//!
//! This shows the recommended `iter_custom` pattern for tracking memory
//! allocations, plus how to debug unexpected allocations with the
//! `panic_on_next_alloc` feature.
//!
//! Criterion is configured with a small measurement budget so the example runs
//! quickly and deterministically as a smoke test; a real benchmark would use
//! `Criterion::default()`.
//!
//! To run the `panic_on_next_alloc` functionality, enable the feature:
//! ```bash
//! cargo run --example alloc_tracker_readme --features panic_on_next_alloc
//! ```

use std::hint::black_box;
use std::time::{Duration, Instant};

#[cfg(not(feature = "panic_on_next_alloc"))]
use alloc_tracker::{Allocator, Session};
#[cfg(feature = "panic_on_next_alloc")]
use alloc_tracker::{Allocator, Session, panic_on_next_alloc};
use criterion::Criterion;

#[global_allocator]
static ALLOCATOR: Allocator<std::alloc::System> = Allocator::system();

#[expect(clippy::useless_vec, reason = "example needs to show allocation")]
fn main() {
    let session = Session::new();
    let operation = session.operation("my_operation");

    let mut criterion = Criterion::default()
        .warm_up_time(Duration::from_millis(100))
        .measurement_time(Duration::from_millis(500))
        .sample_size(10)
        .without_plots();
    criterion.bench_function("my_operation", |b| {
        b.iter_custom(|iters| {
            let start = Instant::now();
            let _span = operation.measure_process().iterations(iters);
            for _ in 0..iters {
                black_box(vec![1, 2, 3, 4, 5]); // This allocates memory
            }
            start.elapsed()
        });
    });

    // When `session` is dropped it prints a human-readable summary to stdout and
    // writes machine-readable JSON files (one per operation) into the Cargo
    // target directory: target/alloc_tracker/<operation>.json

    // Debugging unexpected allocations (only with feature enabled)
    #[cfg(feature = "panic_on_next_alloc")]
    {
        // Enable panic on next allocation.
        panic_on_next_alloc(true);

        // Any allocation attempt will now panic with a descriptive message
        // let _vec = vec![1, 2, 3]; // This would panic and auto-reset the flag!

        // Disable to allow allocations again.
        panic_on_next_alloc(false);
        let _vec = vec![1, 2, 3]; // This is safe
    }

    #[cfg(not(feature = "panic_on_next_alloc"))]
    {
        println!("To test panic_on_next_alloc functionality, run with:");
        println!("cargo run --example alloc_tracker_readme --features panic_on_next_alloc");
        let _vec = vec![1, 2, 3]; // Regular allocation without panic functionality
    }
}