Skip to main content

spec_stream_cache/
block.rs

1use spec_stream_core::TokenId;
2
3/// Unique physical block index in the memory pool.
4pub type PhysicalBlockId = usize;
5
6/// Size of a block in number of tokens (typically 16, 32, or 64).
7pub const DEFAULT_BLOCK_SIZE: usize = 16;
8
9/// Represents a physical memory block storing KV-tensors for a fixed number of tokens.
10#[derive(Debug, Clone)]
11pub struct PhysicalBlock {
12    pub id: PhysicalBlockId,
13    pub block_size: usize,
14    /// Reference count for Copy-on-Write and prefix sharing.
15    pub ref_count: usize,
16    /// Number of valid tokens currently stored in this block.
17    pub num_tokens: usize,
18    /// Cached hash of the token sequence prefix stored in this block (for prefix caching).
19    pub prefix_hash: Option<u64>,
20    /// Token IDs stored in this block (for tracking and prefix matching).
21    pub tokens: Vec<TokenId>,
22}
23
24impl PhysicalBlock {
25    pub fn new(id: PhysicalBlockId, block_size: usize) -> Self {
26        Self {
27            id,
28            block_size,
29            ref_count: 0,
30            num_tokens: 0,
31            prefix_hash: None,
32            tokens: Vec::with_capacity(block_size),
33        }
34    }
35
36    #[inline]
37    pub fn is_full(&self) -> bool {
38        self.num_tokens >= self.block_size
39    }
40
41    #[inline]
42    pub fn is_free(&self) -> bool {
43        self.ref_count == 0
44    }
45
46    #[inline]
47    pub fn reset(&mut self) {
48        self.ref_count = 0;
49        self.num_tokens = 0;
50        self.prefix_hash = None;
51        self.tokens.clear();
52    }
53}