Struct Statistics 

pub struct Statistics<I> { /* private fields */ }

Wrapper that records allocation activity in AllocStats.

Send + Sync if I: Send + Sync. Atomic counters are themselves Sync.

Accounting invariant

Statistics records bytes by the layout the outer caller passed in. Wrappers below Statistics that pass the layout through unchanged (PoisonOnFree, Quarantine, Watermark) preserve this — the bytes counted equal the bytes the caller requested. Wrappers below Statistics that inflate the inner layout (Canary, CacheJitter, HugePageAligned, SplitMetadata) consume more inner-allocator bytes than the counter reports; the counter therefore reflects “bytes the user asked for”, not “bytes the underlying region holds”. If you need the latter, wrap Statistics INSIDE the layout-inflating wrapper: Canary<Statistics<Slab<T>>> counts what Slab actually carved. The recommended position for Statistics (Statistics<PoisonOnFree<Slab>>) treats “bytes the user asked for” as the right number to surface to operators; flip the nesting only if you specifically need physical accounting.

API-misuse compile-failures (pinned)

Statistics<I> inherits the Sync property of its inner allocator. Wrapping a !Sync allocator (such as Slab, whose UnsafeCell free list head makes it !Sync by design) does not silently upgrade it to Sync. Calling stats() on a shared reference across threads when the inner is !Sync is therefore rejected at compile time:

// FAILS TO COMPILE: `Slab` is `!Sync` (UnsafeCell on the freelist
// head), so `Statistics<Slab<...>>` is also `!Sync`, and
// `assert_sync` rejects it.
use forge_alloc::InlineBacked;
use forge_alloc::Statistics;
use forge_alloc::Slab;
fn assert_sync<T: Sync>() {}
assert_sync::<Statistics<Slab<u64, InlineBacked<512>>>>();

Implementations

impl<I> Statistics<I>

pub const fn new(inner: I) -> Self

Wrap.

pub fn stats(&self) -> &AllocStats

Borrow the counters. Read-only access — counters are updated by the allocator’s own methods.

pub fn inner(&self) -> &I

Borrow the inner allocator.

Trait Implementations

impl<I: Allocator> Allocator for Statistics<I>

fn allocate(&self, layout: NonZeroLayout) -> Result<NonNull<[u8]>, AllocError>

Allocate a block satisfying layout. The returned slice’s length is at least layout.size() but may be larger.

unsafe fn usable_size( &self, ptr: NonNull<u8>, layout: NonZeroLayout, ) -> Option<usize>

Usable size of an existing allocation, if the allocator can report it. Defaults to None — implementors that track usable size override.

fn capacity_bytes(&self) -> Option<usize>

Total bytes this allocator can issue, if bounded. None for unbounded allocators like System. Used by Watermark to compute thresholds.

fn corruption_events(&self) -> u64

Detected freelist / metadata corruption events observed by this allocator since construction.

fn allocate_zeroed( &self, layout: NonZeroLayout, ) -> Result<NonNull<[u8]>, AllocError>

Allocate a zero-initialized block.

unsafe fn grow( &self, ptr: NonNull<u8>, old: NonZeroLayout, new: NonZeroLayout, ) -> Result<NonNull<[u8]>, AllocError>

Grow an allocation in place if possible, otherwise allocate-copy-free.

unsafe fn shrink( &self, ptr: NonNull<u8>, old: NonZeroLayout, new: NonZeroLayout, ) -> Result<NonNull<[u8]>, AllocError>

Shrink an allocation in place if possible, otherwise allocate-copy-free.

fn reset(&mut self) -> Result<(), AllocError>

Reclaim everything previously allocated. Default impl returns AllocError — only arena-style allocators implement a meaningful reset.

impl<I: Allocator> Deallocator for Statistics<I>

unsafe fn deallocate(&self, ptr: NonNull<u8>, layout: NonZeroLayout)

Release a previously allocated block.

impl<I: FixedRange> FixedRange for Statistics<I>

fn commit(&self, offset: usize, len: usize) -> Result<(), AllocError>

Pass-through forward so a commit-aware consumer reaches the inner backing when this wrapper sits over a lazy_commit MmapBacked.

fn base(&self) -> NonNull<u8>

First byte of the owned address range.

fn size(&self) -> usize

Length in bytes of the owned address range.

fn contains(&self, ptr: NonNull<u8>) -> bool

Whether ptr lies within [base, base + size).