kevy_alloc/
stats.rs

1//! The accounting contract, as a type.
2//!
3//! `bench/V5-ACCOUNTING-CONTRACT.md` §1 fixes these fields before this
4//! crate existed, because both v5 RFCs state their ceiling as a
5//! decomposition and a gate that cannot assert *"these terms sum to the
6//! observed gap"* cannot check the only claim that matters.
7//!
8//! # The identity
9//!
10//! ```text
11//! mapped == live + rounding + cache + span_free + virgin
12//!         + hysteresis + segment_overhead
13//! ```
14//!
15//! Exact, with no tolerance. Every mapped byte is in exactly one of
16//! those states by construction, so a mismatch means something is
17//! miscounted — and unexplained bytes are precisely where glibc's 2.24×
18//! was hiding.
19//!
20//! # Two terms the contract did not have at T0
21//!
22//! T0 fixed five terms. Building the geometry showed the partition was
23//! not a partition, so two were added — declared here with the reason,
24//! which is what the contract requires (silently widening it is what is
25//! banned, not changing it):
26//!
27//! - **`virgin`** — spans hand out slots by bumping a cursor, so the
28//!   region above the cursor is *mapped but never touched*, and
29//!   therefore not resident. Folding it into slack would have made the
30//!   slack term look like memory when it is only address space. This
31//!   split is the difference between a number that predicts RSS and one
32//!   that does not.
33//! - **`segment_overhead`** — one span per segment holds the header.
34//!   1.6 % of every segment, structural and knowable, so it is named
35//!   rather than absorbed into a neighbour.
36
37/// A snapshot of where every mapped byte is.
38#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
39pub struct Stats {
40    /// Total bytes mapped from the OS. The anchor.
41    pub mapped: u64,
42    /// Sum of `Layout::size()` over live allocations — what callers
43    /// actually asked for, unrounded.
44    pub live: u64,
45    /// Sum of (slot size − requested size) over live allocations.
46    pub rounding: u64,
47    /// Bytes parked on foreign-free lists, waiting to be drained home.
48    pub cache: u64,
49    /// Free slots in spans that were handed out before and returned to
50    /// the free pool: touched, therefore resident.
51    pub span_free: u64,
52    /// Free slots whose pages have been handed back to the OS while
53    /// their span stays live — mapped, not resident. The v2 term: this
54    /// is what page-granular reclaim produces, and it did not exist
55    /// while the reclaim unit was the whole span.
56    pub returned: u64,
57    /// Span bytes at or above the bump cursor — mapped, never touched,
58    /// not resident.
59    pub virgin: u64,
60    /// Whole spans with nothing live, retained rather than released.
61    pub hysteresis: u64,
62    /// Segment headers.
63    pub segment_overhead: u64,
64    /// Live allocations served by direct mapping rather than a class.
65    pub large_count: u64,
66    /// Spans currently assigned to a size class. Exported because "did
67    /// we keep claiming fresh spans past reusable ones" is not visible
68    /// in any byte count — the identity balances either way.
69    pub spans_assigned: u64,
70}
71
72impl Stats {
73    /// The sum the identity asserts. Kept separate from [`Self::mapped`]
74    /// so a test can compare the two rather than trusting one.
75    #[must_use]
76    pub fn accounted(&self) -> u64 {
77        self.live
78            + self.rounding
79            + self.cache
80            + self.span_free
81            + self.returned
82            + self.virgin
83            + self.hysteresis
84            + self.segment_overhead
85    }
86
87    /// Whether the identity holds exactly.
88    #[must_use]
89    pub fn balanced(&self) -> bool {
90        self.mapped == self.accounted()
91    }
92
93    /// Bytes we expect to be resident: everything mapped except what was
94    /// never touched or has been handed back to the OS.
95    ///
96    /// An estimate by construction — the kernel decides residency, not
97    /// us — so it is named as a prediction and compared against real RSS
98    /// by the gate rather than substituted for it.
99    #[must_use]
100    pub fn predicted_resident(&self) -> u64 {
101        self.mapped - self.virgin - self.hysteresis - self.returned
102    }
103
104    /// Add another heap's snapshot. Shards report separately; a process
105    /// figure is their sum.
106    pub fn merge(&mut self, other: &Stats) {
107        self.mapped += other.mapped;
108        self.live += other.live;
109        self.rounding += other.rounding;
110        self.cache += other.cache;
111        self.span_free += other.span_free;
112        self.returned += other.returned;
113        self.virgin += other.virgin;
114        self.hysteresis += other.hysteresis;
115        self.segment_overhead += other.segment_overhead;
116        self.large_count += other.large_count;
117        self.spans_assigned += other.spans_assigned;
118    }
119}
120
121#[cfg(test)]
122mod tests {
123    use super::*;
124
125    #[test]
126    fn an_empty_heap_balances() {
127        assert!(Stats::default().balanced());
128    }
129
130    #[test]
131    fn merge_is_additive_in_every_term() {
132        let a = Stats { mapped: 10, live: 4, virgin: 6, ..Stats::default() };
133        let mut sum = a;
134        sum.merge(&a);
135        assert_eq!(sum.mapped, 20);
136        assert_eq!(sum.live, 8);
137        assert_eq!(sum.virgin, 12);
138        assert!(sum.balanced());
139    }
140
141    #[test]
142    fn an_imbalance_is_visible() {
143        let bad = Stats { mapped: 100, live: 1, ..Stats::default() };
144        assert!(!bad.balanced());
145        assert_eq!(bad.accounted(), 1);
146    }
147}
kevy_alloc/stats.rs

kevy_alloc/
stats.rs
