Struct ModAlloc 

pub struct ModAlloc { /* private fields */ }

Global allocator wrapper that tracks allocations.

Install as #[global_allocator] to enable tracking. The wrapper forwards every allocation, deallocation, reallocation, and zero-initialised allocation to std::alloc::System and records the event in four lock-free AtomicU64 counters.

Example

use mod_alloc::ModAlloc;

#[global_allocator]
static GLOBAL: ModAlloc = ModAlloc::new();

fn main() {
    let v: Vec<u8> = vec![0; 1024];
    let stats = GLOBAL.snapshot();
    assert!(stats.alloc_count >= 1);
    drop(v);
}

Implementations

impl ModAlloc

pub const fn new() -> Self

Construct a new ModAlloc allocator wrapper.

All counters start at zero. This function is const, which allows construction in a static for use as #[global_allocator].

Example

use mod_alloc::ModAlloc;

static GLOBAL: ModAlloc = ModAlloc::new();
let stats = GLOBAL.snapshot();
assert_eq!(stats.alloc_count, 0);

Examples found in repository

examples/basic.rs (line 8)

static GLOBAL: ModAlloc = ModAlloc::new();

examples/bench_overhead.rs (line 20)

static GLOBAL: ModAlloc = ModAlloc::new();

pub fn snapshot(&self) -> AllocStats

Snapshot the current counter values.

Each counter is read independently with Relaxed ordering; the resulting AllocStats is a coherent best-effort view but does not represent a single atomic moment in time. For scoped measurement, prefer Profiler.

Example

use mod_alloc::ModAlloc;

let alloc = ModAlloc::new();
let stats = alloc.snapshot();
assert_eq!(stats.alloc_count, 0);

Examples found in repository

examples/bench_overhead.rs (line 40)

fn main() {
    for _ in 0..WARMUP {
        let v: Vec<u8> = Vec::with_capacity(SIZE);
        std::hint::black_box(&v);
    }

    GLOBAL.reset();
    let start = Instant::now();
    for _ in 0..N {
        let v: Vec<u8> = Vec::with_capacity(SIZE);
        std::hint::black_box(&v);
    }
    let elapsed = start.elapsed();

    let snap = GLOBAL.snapshot();
    let per_cycle_ns = elapsed.as_nanos() as f64 / N as f64;

    println!("bench_overhead:");
    println!("  iterations:           {N}");
    println!("  allocation size:      {SIZE} bytes");
    println!("  elapsed:              {elapsed:?}");
    println!("  per alloc+dealloc:    {per_cycle_ns:.1} ns");
    println!();
    println!("counter snapshot after run:");
    println!("  alloc_count:   {}", snap.alloc_count);
    println!("  total_bytes:   {}", snap.total_bytes);
    println!("  current_bytes: {}", snap.current_bytes);
    println!("  peak_bytes:    {}", snap.peak_bytes);
}

examples/basic.rs (line 30)

fn main() {
    let p = Profiler::start();

    let v: Vec<u64> = (0..1_000).collect();
    let sum: u64 = v.iter().sum();
    drop(v);

    let mut owned: Vec<String> = Vec::with_capacity(100);
    for i in 0..100 {
        owned.push(format!("item-{i}"));
    }
    drop(owned);

    let delta = p.stop();
    println!("Profiler delta (alloc/total/current = delta; peak = absolute):");
    println!("  alloc_count:   {}", delta.alloc_count);
    println!("  total_bytes:   {}", delta.total_bytes);
    println!("  current_bytes: {}", delta.current_bytes);
    println!("  peak_bytes:    {}", delta.peak_bytes);

    let snap = GLOBAL.snapshot();
    println!();
    println!("Process-wide snapshot:");
    println!("  alloc_count:   {}", snap.alloc_count);
    println!("  total_bytes:   {}", snap.total_bytes);
    println!("  current_bytes: {}", snap.current_bytes);
    println!("  peak_bytes:    {}", snap.peak_bytes);

    println!();
    println!("(workload checksum: {sum})");
}

pub fn reset(&self)

Reset all counters to zero.

Intended for use at the start of a profile run, before any outstanding allocations exist. Calling reset while allocations are live can cause current_bytes to wrap on subsequent deallocations; the other counters are unaffected.

Example

use mod_alloc::ModAlloc;

let alloc = ModAlloc::new();
alloc.reset();
let stats = alloc.snapshot();
assert_eq!(stats.alloc_count, 0);

Examples found in repository

examples/bench_overhead.rs (line 32)

fn main() {
    for _ in 0..WARMUP {
        let v: Vec<u8> = Vec::with_capacity(SIZE);
        std::hint::black_box(&v);
    }

    GLOBAL.reset();
    let start = Instant::now();
    for _ in 0..N {
        let v: Vec<u8> = Vec::with_capacity(SIZE);
        std::hint::black_box(&v);
    }
    let elapsed = start.elapsed();

    let snap = GLOBAL.snapshot();
    let per_cycle_ns = elapsed.as_nanos() as f64 / N as f64;

    println!("bench_overhead:");
    println!("  iterations:           {N}");
    println!("  allocation size:      {SIZE} bytes");
    println!("  elapsed:              {elapsed:?}");
    println!("  per alloc+dealloc:    {per_cycle_ns:.1} ns");
    println!();
    println!("counter snapshot after run:");
    println!("  alloc_count:   {}", snap.alloc_count);
    println!("  total_bytes:   {}", snap.total_bytes);
    println!("  current_bytes: {}", snap.current_bytes);
    println!("  peak_bytes:    {}", snap.peak_bytes);
}

Trait Implementations

impl Default for ModAlloc

fn default() -> Self

Returns the “default value” for a type.

impl GlobalAlloc for ModAlloc

unsafe fn alloc(&self, layout: Layout) -> *mut u8

Allocates memory as described by the given layout.

unsafe fn alloc_zeroed(&self, layout: Layout) -> *mut u8

Behaves like alloc, but also ensures that the contents are set to zero before being returned.

unsafe fn dealloc(&self, ptr: *mut u8, layout: Layout)

Deallocates the block of memory at the given ptr pointer with the given layout.

unsafe fn realloc( &self, ptr: *mut u8, layout: Layout, new_size: usize, ) -> *mut u8

Shrinks or grows a block of memory to the given new_size in bytes. The block is described by the given ptr pointer and layout.