Expand description
Cache Module
High-performance caching infrastructure for RedDB.
§Components
- sieve: SIEVE page cache for database pages (O(1) operations)
- blob: Byte-oriented L1 cache for exact-key cached blobs
- result: Query result cache with dependency-based invalidation
- aggregates: Precomputed aggregations (COUNT, SUM, AVG, etc.)
- spill: Graph spill-to-disk for memory-limited environments
§Architecture (inspired by Turso/Milvus/Neo4j)
┌────────────────────────────────────────────────────────┐
│ Query Layer │
├────────────────────────────────────────────────────────┤
│ Result Cache │ Materialized Views │ Plan Cache │
├────────────────────────────────────────────────────────┤
│ Aggregation Cache (COUNT/SUM/AVG) │
├────────────────────────────────────────────────────────┤
│ SIEVE Page Cache │ Spill Manager │
├────────────────────────────────────────────────────────┤
│ Storage Engine │
└────────────────────────────────────────────────────────┘Modules§
- aggregates
- Aggregation Cache
- bgwriter
- Background writer task — Post-MVP credibility item.
- blob
- Byte-oriented Blob Cache.
- compressor
- L2 Blob Compressor.
- extended_
ttl - Extended TTL Policy & Effective Expiry
- promotion_
pool - Async promotion pool — turbo module for off-CPU L1 cache promotion.
- result
- Query Result Cache
- ring
- Fixed-size circular page ring used by
super::strategy::BufferAccessStrategy. - sieve
- SIEVE Page Cache
- spill
- Graph Spill Manager
- strategy
- Buffer access strategies for the page cache.
- sweeper
- Bounded Blob Cache sweeper — admin maintenance for L1 expirations and L2 orphan-chain reclamation.
Structs§
- AggCache
Stats - Aggregation cache statistics
- Aggregation
Cache - Cache for precomputed aggregations
- Async
Promotion Pool - Bounded, drop-oldest async promotion pool.
- Blob
Cache - Sharded, byte-bounded blob cache with optional durable L2 backing.
- Blob
Cache Config - Blob
Cache Hit - Blob
Cache Policy - Blob
Cache Put - Blob
Cache Stats - Buffer
Ring - Fixed-capacity circular cache.
- Cache
Config - Cache configuration
- Cache
Key - Cache key for query results
- Cache
Policy - Policy for cache entry behavior
- Cache
Stats - Cache statistics
- Cardinality
Estimate - Cardinality estimator using HyperLogLog-style counting
- Compress
Opts - Configuration knobs for
L2BlobCompressor::compress. - Effective
Expiry - Stateless calculator for effective expiry decisions.
- Extended
TtlPolicy - Extended TTL configuration that augments a base [
BlobCachePolicy]. - L2Blob
Compressor - Stateless compressor for L2 blob payloads.
- Materialized
View Cache - Cache for materialized views
- Materialized
View Def - Definition of a materialized view
- Numeric
Agg - Numeric aggregation value
- Page
Cache - SIEVE Page Cache
- Pool
Opts - Configuration for the promotion pool.
- Promotion
Metrics - Snapshot of the pool’s atomic counters. Returned by
metrics(). - Promotion
Request - A single async promotion request handed to the pool by
BlobCache::get(or, in tests, by the test harness). - Result
Cache - LRU cache for query results with memory management
- Result
Cache Stats - Cache statistics
- Spill
Config - Configuration for the spill manager
- Spill
Manager - Manages memory limits by spilling cold data to disk
- Spill
Stats - Statistics about spill operations
- Spillable
Graph - A graph wrapper that automatically spills to disk when memory limit is reached
Enums§
- AggValue
- Value type for aggregation operations
- Buffer
Access Strategy - How a caller intends to access the page cache.
- Cache
Error - Compress
Error - Errors produced by the compressor.
- Compressed
- Storage-ready representation of a blob payload after the compressor has
inspected it.
Rawis byte-equivalent to the input;Zstdcarries an encoded payload plus the original byte length for verification. - Expiry
Decision - Outcome of an
EffectiveExpiry::computecall. - L1Admission
- L2Compression
- Switch for L2 zstd compression (issue #192, lane 2/5).
- Refresh
Policy - How to refresh a materialized view
- Schedule
Outcome - Result of
AsyncPromotionPool::schedule. - Spill
Error - Error types for spill operations
Constants§
- DEFAULT_
BLOB_ L1_ BYTES_ MAX - DEFAULT_
BLOB_ L2_ BYTES_ MAX - DEFAULT_
BLOB_ MAX_ NAMESPACES - METRIC_
CACHE_ BLOB_ L1_ BYTES_ IN_ USE - METRIC_
CACHE_ BLOB_ L2_ BYTES_ IN_ USE - METRIC_
CACHE_ BLOB_ L2_ FULL_ REJECTIONS_ TOTAL - METRIC_
CACHE_ VERSION_ MISMATCH_ TOTAL
Functions§
- archive_
blob_ cache_ l2 - Archive the L2 pager file + control sidecar to
backendunder{prefix}l2.pagerand{prefix}l2.ctl. Returns the number of files uploaded (0..=2). - restore_
blob_ cache_ l2 - Restore the L2 pager file + control sidecar from
backend’s{prefix}l2.pagerand{prefix}l2.ctlkeys intol2_path(and its<l2_path>.blob-cache.ctlsibling). Returns the number of files downloaded.
Type Aliases§
- PageId
- Page identifier type
- Promotion
Executor - The closure that actually performs the L1 promotion. Injected at
construction so this module has no compile-time dependency on
BlobCache.