Expand description
One coherent, allocation-free observation of a counted engine’s heap
and its held charges (docs/plans/extract.md X12, X13). The engine’s
counting allocator and official thread-registration/account hooks feed
this test-only ledger (docs/plans/batch.md 2.11’s tally row).
- Registration is
crate::counted::count_this_thread: a test registers each engine thread before its measured work (Tokio’son_thread_starttakes it as is); a thread never registered, the test runner’s or a peer’s, is never counted. - The heap is the aggregate of every registered thread, one sum, so a block made on one thread and freed on another balances; no thread’s signed count is read as what it owns.
- Conservative: a block counts from before
Systemis asked for it until afterSystemhas freed it (crate::counted::Tally::growing,crate::counted::Tally::shrank), so between two events the ledger never holds less than the registered threads’ live heap, however their allocations interleave: what the lock orders is the count, and the count brackets each real transition. - Charges are told to the same ledger (
Ledger::charge,Ledger::release): what a budget holds, never a reservation’s unused part or a cap.
Every event, a block or a charge, goes through one short critical
section, so each event sees the heap and the charges as one state, in
one total order: the residual it records, the heap’s rise since
Ledger::arm less the charges’ rise, is of one instant, never two
peaks read at different times. The critical section
is a spin on an atomic flag, which allocates nothing and cannot fail;
no event formats, allocates or panics, so a global allocator may call
it (crate::counted::Tally). Each event is an observation: a
residual past Ledger::arm’s uncharged allowance is a violation, the
first one kept with its event number.
Structs§
- Ledger
- The aggregate heap and charges of the registered threads, observed at
each event.
costis the charge unit of a block’s size (the core’sheap_cost, which the testkit does not link): a test passes it. - Observation
- One event’s view of the ledger, or a reading of it: one state.
- Violation
- An event whose heap passed its charges plus the allowance.