Struct BlockAllocator 

pub struct BlockAllocator { /* private fields */ }

LIFO free-list block allocator. O(1) allocate / free, no fragmentation (all blocks are uniform size).

capacity is the total physical block count baked into the pool at load time. The allocator is independent per-model (block index space is not portable across models).

Implementations

impl BlockAllocator

pub fn new(num_blocks: u32) -> Self

Create a fresh allocator. All num_blocks blocks start free. Free-list is built so allocate() returns block 0 first, then 1, etc. — predictable for tests and ensures the lower physical blocks see the most reuse (better cache locality on M1’s SLC).

pub fn allocate(&mut self) -> Result<u32>

Allocate a single physical block. Returns Err when the pool is exhausted — caller is expected to refuse the request and queue it (or evict another seq, when that’s wired up).

New block starts with ref_count = 1. Drop one ref via free() to return it to the pool, or call acquire() for additional sharers.

pub fn allocate_n(&mut self, n: usize) -> Result<Vec<u32>>

Bulk allocate. Atomic: either all n succeed or none are taken. Each returned block starts at ref_count = 1.

pub fn try_acquire_by_hash(&mut self, hash: BlockHash) -> Option<u32>

Look up a hash in the prefix-cache table. If the hash maps to a physical block (live or soft-free), bump its ref count and return the block id. A soft-free block (ref=0 in free_list) is resurrected — pulled out of the free list and ref set to 1. Returns None on cache miss.

pub fn register_block_hash(&mut self, block: u32, hash: BlockHash)

Associate a hash with a block (after its content is written). If the block already had a hash, the old mapping is replaced. Block must currently be live (ref ≥ 1).

pub fn hash_table_size(&self) -> usize

Read accessor for tests / debugging.

pub fn acquire(&mut self, block: u32)

Increment the ref count for an already-allocated block. Used by prefix-caching paths when a new sequence wants to share a block that’s already resident from a prior request.

Panics in debug builds if the block is not currently allocated (ref_count==0) — a release-build path that calls acquire on a free block is a memory-safety bug we’d rather catch loudly.

pub fn acquire_many(&mut self, blocks: &[u32])

Bulk acquire — convenience for prefix-cache hit paths that take a list of physical block ids to share.

pub fn free(&mut self, blocks: &[u32])

Drop one ref from each block. Blocks whose ref_count hits 0 are returned to the free list and become available for the next allocate* call.

Pre-prefix-cache callers see no behavioural change: every block they hold starts at ref=1 (from allocate), and free drops it to 0 — physically frees on the same call, same as before.

pub fn ref_count(&self, block: u32) -> u16

Read current ref count for a block. 0 means free, ≥1 means in use by that many sequences.

pub fn free_count(&self) -> usize

pub fn capacity(&self) -> u32

pub fn peak_in_use(&self) -> usize