Struct KvBlockPool 

pub struct KvBlockPool { /* private fields */ }

A bounded pool of fixed-size KV-cache blocks (in positions) shared across many KvCache instances, typically one pool per server process. Each KvCache::with_pool acquires one block up front and one more each time it grows past its currently held capacity; free_blocks is therefore a live, accurate admission-control signal – a caller can check it before accepting a new request rather than discovering exhaustion only after committing memory.

Implementations

impl KvBlockPool

pub fn new(block_size: usize, total_blocks: usize) -> Self

block_size positions per block, total_blocks blocks in the whole shared budget (so block_size * total_blocks positions total, across however many caches draw from this pool at once).

pub fn block_size(&self) -> usize

pub fn total_blocks(&self) -> usize

pub fn free_blocks(&self) -> usize

pub fn resize(&mut self, total_blocks: usize) -> Result<(), usize>

Re-budget the pool.

The pool is an accounting budget, not an allocator: each KvCache owns its own buffer and this counts how many blocks the deployment has promised. So a resize is arithmetic, with one rule that is not.

Shrinking below what is currently held is REFUSED and the pool is left exactly as it was. free_blocks would have to go negative to represent it, and the alternative – clamping it to zero – silently over-promises: the caches already holding those blocks do not give them back, so every later try_acquire would be deciding against a budget that does not describe the memory in use.

Returns the number of blocks currently held when it refuses, so the caller can say what the floor actually is rather than making the operator find it by being rejected.