Struct BlockManager 

pub struct BlockManager<T: BlockMetadata> { /* private fields */ }

Manages the full block lifecycle across three pool tiers: reset (free), active (in-use), and inactive (cached, evictable).

Thread-safe: allocation is serialised via an internal Mutex; individual pools use their own internal locking.

Construct via BlockManager::builder().

Implementations

impl<T: BlockMetadata> BlockManager<T>

pub fn builder() -> BlockManagerConfigBuilder<T>

Create a new builder for BlockManager.

Example

let tracker = FrequencyTrackingCapacity::Medium.create_tracker();
let registry = BlockRegistry::builder().frequency_tracker(tracker).build();

let manager = BlockManager::builder()
    .block_count(1000)
    .registry(registry)
    .with_multi_lru_backend()
    .build()?;

pub fn allocate_blocks(&self, count: usize) -> Option<Vec<MutableBlock<T>>>

Allocate count mutable blocks, drawing first from the reset pool then evicting from the inactive pool if needed.

Returns None if fewer than count blocks are available across both pools.

pub fn allocate_blocks_with_evictions( &self, count: usize, ) -> Option<(Vec<MutableBlock<T>>, Vec<SequenceHash>)>

Like allocate_blocks but also reports the SequenceHash of each block evicted from the inactive pool to satisfy the allocation. Callers maintaining a shadow view of which registrations are alive (e.g. the mocker’s router-event bridge) can translate these hashes into cache-invalidation events directly, avoiding an O(N) presence scan over the registry.

pub fn reset_inactive_pool(&self) -> Result<(), BlockManagerResetError>

Drain the inactive pool, returning all blocks to the reset pool.

1. Acquires the inactive pool lock and allocates all blocks.
2. Releases the lock.
3. Drops the allocated blocks (RAII returns them to reset).
4. Verifies the reset pool contains the expected total.

Returns an error under contention when blocks are in active use.

pub fn register_blocks( &self, blocks: Vec<CompleteBlock<T>>, ) -> Vec<ImmutableBlock<T>>

Register a batch of completed blocks, returning immutable handles.

pub fn register_block(&self, block: CompleteBlock<T>) -> ImmutableBlock<T>

Register a single completed block and return an immutable handle.

Deduplication is governed by the configured BlockDuplicationPolicy.

pub fn match_blocks(&self, seq_hash: &[SequenceHash]) -> Vec<ImmutableBlock<T>>

Linear prefix match: walks seq_hash left-to-right, stopping on first miss.

Checks the active pool first, then the inactive pool for remaining hashes.

pub fn scan_matches( &self, seq_hashes: &[SequenceHash], touch: bool, ) -> HashMap<SequenceHash, ImmutableBlock<T>>

Scatter-gather scan: finds all blocks matching any hash, without stopping on misses.

Returns a map of found hashes to immutable handles.

pub fn total_blocks(&self) -> usize

Total number of blocks managed (constant after construction).

pub fn available_blocks(&self) -> usize

Blocks available for allocation (reset + inactive pools).

pub fn block_size(&self) -> usize

Tokens per block (constant after construction).

pub fn duplication_policy(&self) -> &BlockDuplicationPolicy

Current duplication policy.

pub fn block_registry(&self) -> &BlockRegistry

Reference to the shared block registry.

pub fn metrics(&self) -> &Arc<BlockPoolMetrics>

Reference to the block pool metrics.