pub struct BlockAllocator {
pub block_size: usize,
pub total_blocks: usize,
/* private fields */
}Expand description
Central allocator managing the physical pool of KV-cache blocks.
Fields§
§block_size: usize§total_blocks: usizeImplementations§
Source§impl BlockAllocator
impl BlockAllocator
Sourcepub fn new(total_blocks: usize, block_size: usize) -> BlockAllocator
pub fn new(total_blocks: usize, block_size: usize) -> BlockAllocator
Initializes a pool with total_blocks of capacity block_size tokens each.
pub fn with_default_block_size(total_blocks: usize) -> BlockAllocator
Sourcepub fn num_free_blocks(&self) -> usize
pub fn num_free_blocks(&self) -> usize
Number of physical blocks currently available for allocation.
Sourcepub fn num_allocated_blocks(&self) -> usize
pub fn num_allocated_blocks(&self) -> usize
Number of physical blocks currently in use.
Sourcepub fn num_prefix_entries(&self) -> usize
pub fn num_prefix_entries(&self) -> usize
Number of distinct prefix entries cached.
Sourcepub fn allocate(&mut self) -> Result<usize, CacheError>
pub fn allocate(&mut self) -> Result<usize, CacheError>
Allocates an empty physical block from the free list.
Sourcepub fn clone_block(&mut self, src_block_id: usize) -> Result<usize, CacheError>
pub fn clone_block(&mut self, src_block_id: usize) -> Result<usize, CacheError>
Duplicates an existing physical block into a new block with ref_count = 1 (Copy-on-Write).
Sourcepub fn inc_ref(&mut self, block_id: usize) -> Result<(), CacheError>
pub fn inc_ref(&mut self, block_id: usize) -> Result<(), CacheError>
Increments ref_count for sharing an existing block (e.g. prompt prefix).
Sourcepub fn free(&mut self, block_id: usize) -> Result<(), CacheError>
pub fn free(&mut self, block_id: usize) -> Result<(), CacheError>
Decrements ref_count and frees the block if ref_count hits zero.
Sourcepub fn register_prefix(&mut self, hash: u64, block_id: usize)
pub fn register_prefix(&mut self, hash: u64, block_id: usize)
Registers a full block into the prefix cache for reuse.
Sourcepub fn find_prefix(&mut self, hash: u64) -> Option<usize>
pub fn find_prefix(&mut self, hash: u64) -> Option<usize>
Searches for an existing shared block by prefix hash.
Sourcepub fn get_block(&self, block_id: usize) -> Result<&PhysicalBlock, CacheError>
pub fn get_block(&self, block_id: usize) -> Result<&PhysicalBlock, CacheError>
Returns a reference to a physical block.
Sourcepub fn get_block_mut(
&mut self,
block_id: usize,
) -> Result<&mut PhysicalBlock, CacheError>
pub fn get_block_mut( &mut self, block_id: usize, ) -> Result<&mut PhysicalBlock, CacheError>
Returns a mutable reference to a physical block.
Sourcepub fn defragment_free_list(&mut self)
pub fn defragment_free_list(&mut self)
Defragments the free list by sorting block IDs so future allocations favor lowest contiguous physical pages.
Sourcepub fn utilization_ratio(&self) -> f32
pub fn utilization_ratio(&self) -> f32
Computes pool utilization ratio between 0.0 (empty) and 1.0 (fully saturated).
Sourcepub fn fragmentation_ratio(&self) -> f32
pub fn fragmentation_ratio(&self) -> f32
Computes memory fragmentation ratio of the free block list. Returns 0.0 when free blocks form a single contiguous block range, higher when scattered.
Source§impl BlockAllocator
impl BlockAllocator
Sourcepub fn export_prefix_snapshot(&self) -> PrefixCacheSnapshot
pub fn export_prefix_snapshot(&self) -> PrefixCacheSnapshot
Exports all active prefix cache entries into a snapshot.
Sourcepub fn import_prefix_snapshot(
&mut self,
snapshot: &PrefixCacheSnapshot,
) -> Result<usize, CacheError>
pub fn import_prefix_snapshot( &mut self, snapshot: &PrefixCacheSnapshot, ) -> Result<usize, CacheError>
Imports warm prefix entries from a snapshot into the allocator pool. Returns the number of prefix blocks successfully restored.