Skip to content

Block Cache

Tiered LRU cache for SSTable data blocks, indexes, and bloom filters.

BlockCache(data_maxsize=256, index_maxsize=64, bloom_maxsize=64)

Tiered thread-safe LRU cache.

Eviction priority (first evicted → last evicted): data blocks → indexes → bloom filters

Initialize a three-tier LRU block cache.

Parameters:

Name Type Description Default
data_maxsize int

Maximum number of data block entries to cache.

 256
index_maxsize int

Maximum number of sparse index entries to cache.

 64
bloom_maxsize int

Maximum number of bloom filter entries to cache.

 64
Source code in app/cache/block.py 
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
def __init__(
    self,
    data_maxsize: int = 256,
    index_maxsize: int = 64,
    bloom_maxsize: int = 64,
) -> None:
    """Initialize a three-tier LRU block cache.

    Args:
        data_maxsize: Maximum number of data block entries to cache.
        index_maxsize: Maximum number of sparse index entries to cache.
        bloom_maxsize: Maximum number of bloom filter entries to cache.
    """
    self._data: LRUCache[tuple[FileID, Offset], bytes] = LRUCache(
        maxsize=data_maxsize,
    )
    self._index: LRUCache[tuple[FileID, Offset], bytes] = LRUCache(
        maxsize=index_maxsize,
    )
    self._bloom: LRUCache[tuple[FileID, Offset], bytes] = LRUCache(
        maxsize=bloom_maxsize,
    )
    self._lock = threading.Lock()

get(file_id, offset)

Return cached entry or None.

Source code in app/cache/block.py 
66
67
68
69
70
71
72
def get(self, file_id: FileID, offset: Offset) -> bytes | None:
    """Return cached entry or None."""
    with self._lock:
        result: bytes | None = self._tier(offset).get(
            (file_id, offset),
        )
        return result

put(file_id, offset, block)

Insert an entry into the appropriate tier.

Source code in app/cache/block.py 
74
75
76
77
78
79
def put(
    self, file_id: FileID, offset: Offset, block: bytes,
) -> None:
    """Insert an entry into the appropriate tier."""
    with self._lock:
        self._tier(offset)[(file_id, offset)] = block

invalidate(file_id)

Evict all entries (all tiers) belonging to file_id.

Source code in app/cache/block.py 
81
82
83
84
85
86
87
def invalidate(self, file_id: FileID) -> None:
    """Evict all entries (all tiers) belonging to *file_id*."""
    with self._lock:
        for cache in (self._data, self._index, self._bloom):
            keys = [k for k in cache if k[0] == file_id]
            for k in keys:
                del cache[k]

invalidate_all(file_ids)

Evict all entries (all tiers) for any of the given file IDs.

Source code in app/cache/block.py 
89
90
91
92
93
94
95
96
def invalidate_all(self, file_ids: list[FileID]) -> None:
    """Evict all entries (all tiers) for any of the given file IDs."""
    ids = set(file_ids)
    with self._lock:
        for cache in (self._data, self._index, self._bloom):
            keys = [k for k in cache if k[0] in ids]
            for k in keys:
                del cache[k]