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();

examples/backtraces.rs (line 13)

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

examples/symbolicate.rs (line 14)

static GLOBAL: mod_alloc::ModAlloc = mod_alloc::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})");
}

examples/backtraces.rs (line 48)

fn main() {
    for _ in 0..1_000 {
        alloc_small();
    }
    for _ in 0..100 {
        alloc_medium();
    }
    for _ in 0..10 {
        alloc_large();
    }

    let snap = GLOBAL.snapshot();
    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!();

    let mut sites = GLOBAL.call_sites();
    sites.sort_by_key(|s| std::cmp::Reverse(s.total_bytes));

    println!("Top 10 call sites by total bytes:");
    println!(
        "{:>10}  {:>14}  {:>4}  {:>18}",
        "count", "total_bytes", "frm", "top frame"
    );
    for (rank, site) in sites.iter().take(10).enumerate() {
        println!(
            "{rank:>2}: {count:>6}  {bytes:>14}  {frm:>4}  {top:#018x}",
            rank = rank,
            count = site.count,
            bytes = site.total_bytes,
            frm = site.frame_count,
            top = site.frames[0],
        );
    }
}

examples/symbolicate.rs (line 52)

fn main() {
    for _ in 0..500 {
        alloc_small();
    }
    for _ in 0..100 {
        alloc_medium();
    }
    for _ in 0..10 {
        alloc_large();
    }

    let mut report = GLOBAL.symbolicated_report();
    report.sort_by_key(|s| std::cmp::Reverse(s.total_bytes));

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

    println!("Top call sites by total bytes:");
    println!(
        "{:>2}  {:>10}  {:>14}  top frame",
        "#", "count", "total_bytes"
    );
    for (rank, site) in report.iter().take(10).enumerate() {
        let top = &site.frames[0];
        let name = top.function.as_deref().unwrap_or("<unresolved>");
        let loc = match (top.file.as_ref(), top.line) {
            (Some(f), Some(l)) => format!("  {}:{}", f.display(), l),
            _ => String::new(),
        };
        println!(
            "{rank:>2}  {count:>10}  {bytes:>14}  {name}{loc}",
            rank = rank,
            count = site.count,
            bytes = site.total_bytes,
            name = name,
            loc = loc,
        );
        // Show inlined expansions if any.
        for inlined in site.frames.iter().skip(1).take_while(|f| f.inlined) {
            let n = inlined.function.as_deref().unwrap_or("<unresolved>");
            println!("        inlined: {n}");
        }
    }
}

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);
}

pub fn call_sites(&self) -> Vec<CallSiteStats>

Available on crate feature backtraces only.

Drain the per-call-site aggregation table into a Vec.

Available only with the backtraces cargo feature. The returned vector contains one CallSiteStats per unique call site observed since the table was first written. Each row carries up to 8 raw return addresses (top of stack first), the number of allocations attributed to that site, and the total bytes.

Symbolication (resolving addresses to function names) lands in v0.9.2. This method exposes raw addresses only.

Example

use mod_alloc::ModAlloc;

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

let _v: Vec<u8> = vec![0; 1024];
for site in GLOBAL.call_sites() {
    println!("{} allocs, {} bytes at {:#x}",
        site.count, site.total_bytes, site.frames[0]);
}

Examples found in repository

examples/backtraces.rs (line 56)

fn main() {
    for _ in 0..1_000 {
        alloc_small();
    }
    for _ in 0..100 {
        alloc_medium();
    }
    for _ in 0..10 {
        alloc_large();
    }

    let snap = GLOBAL.snapshot();
    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!();

    let mut sites = GLOBAL.call_sites();
    sites.sort_by_key(|s| std::cmp::Reverse(s.total_bytes));

    println!("Top 10 call sites by total bytes:");
    println!(
        "{:>10}  {:>14}  {:>4}  {:>18}",
        "count", "total_bytes", "frm", "top frame"
    );
    for (rank, site) in sites.iter().take(10).enumerate() {
        println!(
            "{rank:>2}: {count:>6}  {bytes:>14}  {frm:>4}  {top:#018x}",
            rank = rank,
            count = site.count,
            bytes = site.total_bytes,
            frm = site.frame_count,
            top = site.frames[0],
        );
    }
}

pub fn symbolicated_report(&self) -> Vec<SymbolicatedCallSite>

Available on crate feature symbolicate only.

Drain the per-call-site table and symbolicate each frame against the running binary’s own debug info.

Available only with the symbolicate cargo feature, which also implies backtraces. Returns one SymbolicatedCallSite per unique call site, each carrying resolved function names plus (where available) source file and line.

Allocates. Safe to call from non-allocator contexts only (ordinary user code outside the global-allocator hook).

Results are cached per-address across calls.

Example

use mod_alloc::ModAlloc;

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

let _v: Vec<u8> = vec![0; 1024];
for site in GLOBAL.symbolicated_report() {
    let top = &site.frames[0];
    println!("{} allocs / {} bytes at {}",
        site.count,
        site.total_bytes,
        top.function.as_deref().unwrap_or("<unresolved>"));
}

Examples found in repository

examples/symbolicate.rs (line 49)

fn main() {
    for _ in 0..500 {
        alloc_small();
    }
    for _ in 0..100 {
        alloc_medium();
    }
    for _ in 0..10 {
        alloc_large();
    }

    let mut report = GLOBAL.symbolicated_report();
    report.sort_by_key(|s| std::cmp::Reverse(s.total_bytes));

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

    println!("Top call sites by total bytes:");
    println!(
        "{:>2}  {:>10}  {:>14}  top frame",
        "#", "count", "total_bytes"
    );
    for (rank, site) in report.iter().take(10).enumerate() {
        let top = &site.frames[0];
        let name = top.function.as_deref().unwrap_or("<unresolved>");
        let loc = match (top.file.as_ref(), top.line) {
            (Some(f), Some(l)) => format!("  {}:{}", f.display(), l),
            _ => String::new(),
        };
        println!(
            "{rank:>2}  {count:>10}  {bytes:>14}  {name}{loc}",
            rank = rank,
            count = site.count,
            bytes = site.total_bytes,
            name = name,
            loc = loc,
        );
        // Show inlined expansions if any.
        for inlined in site.frames.iter().skip(1).take_while(|f| f.inlined) {
            let n = inlined.function.as_deref().unwrap_or("<unresolved>");
            println!("        inlined: {n}");
        }
    }
}

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.