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/dhat_json.rs (line 15)

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/dhat_json.rs (line 50)

fn main() -> std::io::Result<()> {
    for _ in 0..500 {
        alloc_small();
    }
    for _ in 0..100 {
        alloc_medium();
    }
    for _ in 0..10 {
        alloc_large();
    }

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

    let path = std::path::Path::new("dhat-heap.json");
    GLOBAL.write_dhat_json(path)?;

    let abs = std::fs::canonicalize(path).unwrap_or_else(|_| path.to_path_buf());
    println!("wrote {}", abs.display());
    println!("open it in dh_view.html to inspect.");
    Ok(())
}

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

pub fn dhat_json_string(&self) -> String

Available on crate feature dhat-compat only.

Render the per-call-site report as a DHAT-compatible JSON string.

Available only with the dhat-compat cargo feature (which implies backtraces). When the symbolicate feature is also active, frame strings carry function names and (where available) source file and line; otherwise they carry raw hex addresses.

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

The output schema (dhatFileVersion: 2, mode: "rust-heap") matches the format consumed by the upstream dh_view.html viewer shipped with Valgrind.

Example

use mod_alloc::ModAlloc;

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

let _v: Vec<u8> = vec![0; 1024];
let json = GLOBAL.dhat_json_string();
assert!(json.contains("\"dhatFileVersion\":2"));

pub fn write_dhat_json<P: AsRef<Path>>(&self, path: P) -> Result<()>

Available on crate feature dhat-compat only.

Render the per-call-site report and write it to path as DHAT-compatible JSON.

Available only with the dhat-compat cargo feature. Mirrors dhat-rs’s convention of writing dhat-heap.json to the current directory; pass that path to drop a file the upstream viewer will load directly.

Allocates. Safe to call from non-allocator contexts only.

Example

use mod_alloc::ModAlloc;

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

let _v: Vec<u8> = vec![0; 1024];
GLOBAL.write_dhat_json("dhat-heap.json")?;

Examples found in repository

examples/dhat_json.rs (line 57)

fn main() -> std::io::Result<()> {
    for _ in 0..500 {
        alloc_small();
    }
    for _ in 0..100 {
        alloc_medium();
    }
    for _ in 0..10 {
        alloc_large();
    }

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

    let path = std::path::Path::new("dhat-heap.json");
    GLOBAL.write_dhat_json(path)?;

    let abs = std::fs::canonicalize(path).unwrap_or_else(|_| path.to_path_buf());
    println!("wrote {}", abs.display());
    println!("open it in dh_view.html to inspect.");
    Ok(())
}

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.