Struct AllocProfiler

pub struct AllocProfiler<Alloc = System> { /* private fields */ }

Measures GlobalAlloc memory usage.

Examples

The default usage is to create a #[global_allocator] that wraps the System allocator with AllocProfiler::system():

use std::collections::*;
use divan::AllocProfiler;

#[global_allocator]
static ALLOC: AllocProfiler = AllocProfiler::system();

fn main() {
    divan::main();
}

#[divan::bench(types = [
    Vec<i32>,
    LinkedList<i32>,
    HashSet<i32>,
])]
fn from_iter<T>() -> T
where
    T: FromIterator<i32>,
{
    (0..100).collect()
}

#[divan::bench(types = [
    Vec<i32>,
    LinkedList<i32>,
    HashSet<i32>,
])]
fn drop<T>(bencher: divan::Bencher)
where
    T: FromIterator<i32>,
{
    bencher
        .with_inputs(|| (0..100).collect::<T>())
        .bench_values(std::mem::drop);
}

Wrap other GlobalAlloc implementations like mimalloc with AllocProfiler::new():

use divan::AllocProfiler;
use mimalloc::MiMalloc;

#[global_allocator]
static ALLOC: AllocProfiler<MiMalloc> = AllocProfiler::new(MiMalloc);

See string and collections benchmarks for more examples.

Implementation

Collecting allocation information happens at any point during which Divan is also measuring the time. As a result, counting allocations affects timing.

To reduce Divan’s footprint during benchmarking:

• Allocation information is recorded in thread-local storage to prevent contention when benchmarks involve multiple threads, either through options like threads or internally spawning their own threads.
• It does not check for overflow and assumes it will not happen. This is subject to change in the future.
• Fast thread-local storage access is assembly-optimized on macOS.

Allocation information is the only data Divan records outside of timing, and thus it also has the only code that affects timing. Steps for recording alloc info:

1. Load the thread-local slot for allocation information.

   On macOS, this is via the gs/tpidrro_el0 registers for pthread_getspecific. Although this is not guaranteed as stable ABI, in practice many programs assume these registers store thread-local data. thread_local! is used on all other platforms.

2. Increment allocation operation invocation count and bytes count (a.k.a. size).

Allocation information is recorded in thread-local storage to prevent slowdowns from synchronized sharing when using multiple threads, through options like threads.

Note that allocations in threads not controlled by Divan are not currently counted.

Implementations

impl AllocProfiler

pub const fn system() -> AllocProfiler

Profiles the System allocator.

impl<A> AllocProfiler<A>

pub const fn new(alloc: A) -> AllocProfiler<A>

Profiles a GlobalAlloc.

Trait Implementations

impl<Alloc> Debug for AllocProfiler<Alloc>

where Alloc: Debug,

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<Alloc> Default for AllocProfiler<Alloc>

where Alloc: Default,

fn default() -> AllocProfiler<Alloc>

Returns the “default value” for a type.

impl<A> GlobalAlloc for AllocProfiler<A>

where A: GlobalAlloc,

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 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.

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

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