Skip to main content

Stats

Struct Stats 

Source
#[non_exhaustive]
pub struct Stats { pub mapped: u64, pub live: u64, pub rounding: u64, pub cache: u64, pub span_free: u64, pub returned: u64, pub virgin: u64, pub hysteresis: u64, pub segment_overhead: u64, pub large_count: u64, pub spans_assigned: u64, }
Expand description

A snapshot of where every mapped byte is.

§Examples

use kevy_alloc::{Heap, Stats};
let mut heap = Heap::new(0);
let p = heap.alloc(100, 8).ok_or("no mapping")?;
let s: Stats = heap.snapshot();
assert_eq!(s.live, 100);
assert!(s.balanced());
// SAFETY: `p` came from this heap with this size and alignment.
unsafe { heap.dealloc(p, 100, 8) };

Fields (Non-exhaustive)§

This struct is marked as non-exhaustive
Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.
§mapped: u64

Total bytes mapped from the OS. The anchor.

§Examples

use kevy_alloc::segment::SEGMENT_BYTES;
let mut heap = Heap::new(0);
assert_eq!(heap.snapshot().mapped, 0);
let p = heap.alloc(100, 8).ok_or("no mapping")?;
// the first allocation maps one whole segment
assert_eq!(heap.snapshot().mapped, SEGMENT_BYTES as u64);
// SAFETY: `p` came from this heap with this size and alignment.
unsafe { heap.dealloc(p, 100, 8) };
§live: u64

Sum of Layout::size() over live allocations — what callers actually asked for, unrounded.

§Examples

let mut heap = Heap::new(0);
let p = heap.alloc(100, 8).ok_or("no mapping")?;
assert_eq!(heap.snapshot().live, 100);
// SAFETY: `p` came from this heap with this size and alignment.
unsafe { heap.dealloc(p, 100, 8) };
assert_eq!(heap.snapshot().live, 0);
§rounding: u64

Sum of (slot size − requested size) over live allocations.

§Examples

let mut heap = Heap::new(0);
// 100 bytes are served from the 104-byte class
let p = heap.alloc(100, 8).ok_or("no mapping")?;
assert_eq!(heap.snapshot().rounding, 4);
// SAFETY: `p` came from this heap with this size and alignment.
unsafe { heap.dealloc(p, 100, 8) };
§cache: u64

Bytes parked on foreign-free lists, waiting to be drained home.

§Examples

let mut owner = Heap::new(1);
let mut other = Heap::new(2);
let p = owner.alloc(100, 8).ok_or("no mapping")?;
// SAFETY: `p` came from `owner` with this size and alignment; freeing
// it through another heap is the cross-shard path.
unsafe { other.dealloc(p, 100, 8) };
other.reclaim(); // ships the freed slot home
assert_eq!(owner.snapshot().cache, 104);
owner.drain_foreign();
assert_eq!(owner.snapshot().cache, 0);
§span_free: u64

Free slots in spans that were handed out before and returned to the free pool: touched, therefore resident.

§Examples

let mut heap = Heap::new(0);
let a = heap.alloc(100, 8).ok_or("no mapping")?;
let before = heap.snapshot().span_free;
// SAFETY: `a` came from this heap with this size and alignment.
unsafe { heap.dealloc(a, 100, 8) };
// the freed slot stays mapped and touched, ready for the next request
assert_eq!(heap.snapshot().span_free, before + 104);
§returned: u64

Bytes whose pages have been handed back to the OS — mapped, not resident. The v2 term: this is what page-granular reclaim produces, and it did not exist while the reclaim unit was the whole span.

Two shapes, both genuinely returned: free slots inside a span that is still live, and whole spans emptied and retired. The second used to be filed under hysteresis, so this read 0 while most of the map had in fact gone back.

§Examples

let mut heap = Heap::new(0);
let held: Vec<_> = (0..16_384).map(|_| heap.alloc(64, 8)).collect::<Option<_>>().ok_or("no mapping")?;
for p in held {
    // SAFETY: each came from this heap with this size and alignment.
    unsafe { heap.dealloc(p, 64, 8) };
}
// once they have gone unused for the purge delay
for _ in 0..=kevy_alloc::PURGE_DELAY {
    heap.reclaim();
}
let s = heap.snapshot();
// pages go back only where the system page matches the span geometry
assert_eq!(s.returned > 0, kevy_alloc::os::page_size_matches());
§virgin: u64

Mapped and never touched, therefore not resident: span bytes at or above the bump cursor, and whole spans carved with their segment that no class has ever claimed.

§Examples

let mut heap = Heap::new(0);
let p = heap.alloc(100, 8).ok_or("no mapping")?;
let s = heap.snapshot();
// most of a fresh segment has never been touched
assert!(s.virgin > s.mapped / 2);
// SAFETY: `p` came from this heap with this size and alignment.
unsafe { heap.dealloc(p, 100, 8) };
§hysteresis: u64

Retained rather than released, and therefore still resident: empty spans held for their class through the purge delay, spans whose discard the platform refused, and large mappings parked in the process-wide retention pool.

Every byte here is one the allocator chose to keep. A byte that went back to the OS belongs in Self::returned — the two are opposites, and for the whole v5 arc they were the same number.

§Examples

let mut heap = Heap::new(0);
let held: Vec<_> = (0..16_384).map(|_| heap.alloc(64, 8)).collect::<Option<_>>().ok_or("no mapping")?;
for p in held {
    // SAFETY: each came from this heap with this size and alignment.
    unsafe { heap.dealloc(p, 64, 8) };
}
heap.reclaim();
// inside the purge delay the emptied spans stay with their class
assert!(heap.snapshot().hysteresis > 0);
§segment_overhead: u64

Segment headers.

§Examples

use kevy_alloc::class::SPAN_BYTES;
let mut heap = Heap::new(0);
let p = heap.alloc(100, 8).ok_or("no mapping")?;
// one span of the segment holds its header
assert_eq!(heap.snapshot().segment_overhead, SPAN_BYTES as u64);
// SAFETY: `p` came from this heap with this size and alignment.
unsafe { heap.dealloc(p, 100, 8) };
§large_count: u64

Live allocations served by direct mapping rather than a class.

§Examples

let mut heap = Heap::new(0);
let p = heap.alloc(1 << 20, 8).ok_or("no mapping")?;
// large blocks are counted process-wide, not per heap
assert_eq!(heap.snapshot().large_count, 0);
assert!(kevy_alloc::large_stats().large_count >= 1);
// SAFETY: `p` came from this heap with this size and alignment.
unsafe { heap.dealloc(p, 1 << 20, 8) };
§spans_assigned: u64

Spans currently assigned to a size class. Exported because “did we keep claiming fresh spans past reusable ones” is not visible in any byte count — the identity balances either way.

§Examples

let mut heap = Heap::new(0);
let a = heap.alloc(100, 8).ok_or("no mapping")?;
let b = heap.alloc(4000, 8).ok_or("no mapping")?;
// two classes in use, one span each
assert_eq!(heap.snapshot().spans_assigned, 2);
// SAFETY: both came from this heap with these sizes and alignment.
unsafe {
    heap.dealloc(a, 100, 8);
    heap.dealloc(b, 4000, 8);
}

Implementations§

Source§

impl Stats

Source

pub fn accounted(&self) -> u64

The sum the identity asserts. Kept separate from Self::mapped so a test can compare the two rather than trusting one.

§Examples
use kevy_alloc::Stats;
// The identity this exists to check: every mapped byte is in
// exactly one bucket, so the sum is comparable to `mapped`
// rather than derived from it.
let s = Stats::default();
assert_eq!(s.accounted(), 0);
assert_eq!(s.mapped, 0);
Source

pub fn balanced(&self) -> bool

Whether the identity holds exactly.

§Examples
let mut heap = Heap::new(0);
let p = heap.alloc(3000, 8).ok_or("no mapping")?;
assert!(heap.snapshot().balanced());
// SAFETY: `p` came from this heap with this size and alignment.
unsafe { heap.dealloc(p, 3000, 8) };
assert!(heap.snapshot().balanced());
Source

pub fn predicted_resident(&self) -> u64

Bytes we expect to be resident: everything mapped except what was never touched or has been handed back to the OS.

An estimate by construction — the kernel decides residency, not us — so it is named as a prediction and compared against real RSS by the gate rather than substituted for it.

hysteresis is NOT subtracted, and used to be. That term is what the policy is deliberately holding — empty spans kept for their class, large mappings parked in the retention pool — and holding is the opposite of handing back. Subtracting it made this prediction fall by exactly the amount the retention pool grew, which is the one direction it cannot be right in.

§Examples
let mut heap = Heap::new(0);
let p = heap.alloc(100, 8).ok_or("no mapping")?;
let s = heap.snapshot();
// untouched bytes are mapped but not expected to be resident
assert_eq!(s.predicted_resident(), s.mapped - s.virgin - s.returned);
assert!(s.predicted_resident() < s.mapped);
// SAFETY: `p` came from this heap with this size and alignment.
unsafe { heap.dealloc(p, 100, 8) };
Source

pub fn merge(&mut self, other: &Stats)

Add another heap’s snapshot. Shards report separately; a process figure is their sum.

§Examples
let (mut a, mut b) = (Heap::new(1), Heap::new(2));
let pa = a.alloc(100, 8).ok_or("no mapping")?;
let pb = b.alloc(200, 8).ok_or("no mapping")?;
let mut total = Stats::default();
total.merge(&a.snapshot());
total.merge(&b.snapshot());
assert_eq!(total.live, 300);
assert!(total.balanced());
// SAFETY: each came from its own heap with this size and alignment.
unsafe {
    a.dealloc(pa, 100, 8);
    b.dealloc(pb, 200, 8);
}

Trait Implementations§

Source§

impl Clone for Stats

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl Copy for Stats

Source§

impl Debug for Stats

Source§

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

Formats the value using the given formatter. Read more
Source§

impl Default for Stats

Source§

fn default() -> Self

Returns the “default value” for a type. Read more
Source§

impl Eq for Stats

Source§

impl Hash for Stats

Source§

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher. Read more
1.3.0 · Source§

fn hash_slice<H>(data: &[Self], state: &mut H)
where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher. Read more
Source§

impl PartialEq for Stats

Source§

fn eq(&self, other: &Self) -> bool

Equality operator ==. Read more
1.0.0 (const: unstable) · Source§

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=. Read more
Source§

impl StructuralPartialEq for Stats

Auto Trait Implementations§

§

impl Freeze for Stats

§

impl RefUnwindSafe for Stats

§

impl Send for Stats

§

impl Sync for Stats

§

impl Unpin for Stats

§

impl UnsafeUnpin for Stats

§

impl UnwindSafe for Stats

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.