concinnity_memory/
lib.rs

1//! The engine's allocation layer: what the process is holding, who is holding it,
2//! and the allocators that hand memory out in bulk instead of one block at a
3//! time.
4//!
5//! Five things live here, in files that do not depend on each other:
6//!
7//!   counters   the global heap's live / peak / churn, sharded per thread and
8//!              driven by `TrackingAlloc` (`tracking`)
9//!   ledger     tagged byte accounting -- textures, meshes, audio, scratch --
10//!              in host and device memory, against optional budgets
11//!   arena      a bump allocator for per-frame working memory
12//!   pool       fixed-capacity storage for a population that churns
13//!   inline_vec a sequence that keeps its first element inline, for the many
14//!              per-entity collections that hold exactly one thing
15//!
16//! The counters measure the Rust heap, not "the engine". They see every
17//! allocation the process makes through Rust -- engine, tools, and third-party
18//! crates alike -- and none of the memory Rust never allocated: GPU driver
19//! allocations, mapped asset files, thread stacks, and the binary image itself.
20//! The gap between `MemStats::live_bytes` and the process resident size is that
21//! non-Rust remainder, not untracked engine waste. The ledger is the other half
22//! of that story: it explains a portion of both realms by name, and what it
23//! explains is always a floor, since it holds only what someone reports.
24//!
25//! GPU memory is accounted here and allocated elsewhere, deliberately. A device
26//! allocator returns a heap and an offset rather than a pointer, its frees must
27//! wait for frames in flight to retire, and its placement rules differ per
28//! backend; that belongs behind concinnity-device. What both sides share is the
29//! vocabulary they report into, which is what lets one readout show RAM and VRAM
30//! through the same lens.
31
32#![no_std]
33
34extern crate alloc;
35
36#[cfg(test)]
37extern crate std;
38
39mod arena;
40#[cfg(test)]
41mod bench;
42mod counters;
43mod detail;
44mod inline_vec;
45mod ledger;
46mod pool;
47mod tag;
48mod tracking;
49
50pub use arena::{Arena, ArenaVec};
51pub use counters::MemStats;
52pub use detail::{SizeClass, size_classes};
53pub use inline_vec::{InlineVec, IntoIter as InlineVecIntoIter};
54pub use ledger::{Ledger, LedgerSnapshot};
55pub use pool::{Pool, PoolHandle};
56pub use tag::{MemTag, Realm};
57pub use tracking::TrackingAlloc;
58
59static LEDGER: Ledger = Ledger::new();
60
61/// The tracked heap as of now, or `None` when no binary installed
62/// `TrackingAlloc` as its `#[global_allocator]`.
63pub fn stats() -> Option<MemStats> {
64    tracking::COUNTERS.snapshot()
65}
66
67/// Allocations made since process start, or `None` under the same condition as
68/// `stats`. Cheaper than a full `stats` read; the frame loop samples this around
69/// every system step in dev builds to attribute per-frame allocation churn.
70pub fn alloc_count() -> Option<u64> {
71    tracking::COUNTERS.alloc_count()
72}
73
74/// The process-wide tagged accounting. Subsystems report what they hold into it
75/// and readouts break the process down by tag; unlike `stats`, it is live
76/// whether or not a binary installed the tracking allocator.
77pub fn ledger() -> &'static Ledger {
78    &LEDGER
79}
80
81#[cfg(test)]
82mod tests {
83    use super::*;
84
85    // The one global instance is reachable and is the same one every caller
86    // reports into.
87    #[test]
88    fn the_global_ledger_is_shared_by_every_caller() {
89        ledger().add(MemTag::Other, Realm::Host, 4_096);
90        assert!(ledger().usage(MemTag::Other, Realm::Host).bytes >= 4_096);
91        ledger().release(MemTag::Other, Realm::Host, 4_096);
92    }
93}
concinnity_memory/lib.rs

concinnity_memory/
lib.rs
