Skip to main content

Module ledger

Module ledger 

Source
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’s on_thread_start takes 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 System is asked for it until after System has 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. cost is the charge unit of a block’s size (the core’s heap_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.