concinnity_core/memory/
mod.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
32mod arena;
33#[cfg(test)]
34mod bench;
35mod counters;
36mod detail;
37mod inline_vec;
38mod ledger;
39mod pool;
40mod tag;
41mod tracking;
42
43pub use arena::{Arena, ArenaVec};
44pub use counters::MemStats;
45pub use detail::{SizeClass, size_classes};
46pub use inline_vec::{InlineVec, IntoIter as InlineVecIntoIter};
47pub use ledger::{Ledger, LedgerSnapshot};
48pub use pool::{Pool, PoolHandle};
49pub use tag::{MemTag, Realm};
50pub use tracking::TrackingAlloc;
51
52static LEDGER: Ledger = Ledger::new();
53
54/// The tracked heap as of now, or `None` when no binary installed
55/// `TrackingAlloc` as its `#[global_allocator]`.
56pub fn stats() -> Option<MemStats> {
57    tracking::COUNTERS.snapshot()
58}
59
60/// Allocations made since process start, or `None` under the same condition as
61/// `stats`. Cheaper than a full `stats` read; the frame loop samples this around
62/// every system step in dev builds to attribute per-frame allocation churn.
63pub fn alloc_count() -> Option<u64> {
64    tracking::COUNTERS.alloc_count()
65}
66
67/// The process-wide tagged accounting. Subsystems report what they hold into it
68/// and readouts break the process down by tag; unlike `stats`, it is live
69/// whether or not a binary installed the tracking allocator.
70pub fn ledger() -> &'static Ledger {
71    &LEDGER
72}
73
74#[cfg(test)]
75mod tests {
76    use super::*;
77
78    // The one global instance is reachable and is the same one every caller
79    // reports into.
80    #[test]
81    fn the_global_ledger_is_shared_by_every_caller() {
82        ledger().add(MemTag::Other, Realm::Host, 4_096);
83        assert!(ledger().usage(MemTag::Other, Realm::Host).bytes >= 4_096);
84        ledger().release(MemTag::Other, Realm::Host, 4_096);
85    }
86}
concinnity_core/memory/mod.rs

concinnity_core/memory/
mod.rs
