Module page_cache 

Application-Level Page Cache with Clock-Pro (Recommendation 8)

Problem

SQLite maintains a sophisticated page cache with:

• LRU-K eviction policy
• Dirty page tracking
• Read-ahead for sequential scans

SochDB currently relies on OS page cache (mmap) which:

• Has no application-level control
• Cannot prioritize hot pages
• Has 4KB granularity (vs optimal 64KB for SSTable blocks)

Solution

Clock-Pro algorithm (adaptive replacement cache):

┌─────────────────────────────────────────────────────────┐
│                    Clock-Pro Cache                       │
├─────────────────────────────────────────────────────────┤
│  Hot Ring (frequently accessed)                         │
│    ↻ Clock hand for hot pages                           │
├─────────────────────────────────────────────────────────┤
│  Cold Ring (recently accessed once)                      │
│    ↻ Clock hand for cold pages                          │
├─────────────────────────────────────────────────────────┤
│  Test Ring (ghost entries for adaptive sizing)          │
│    Tracks recently evicted to detect reuse              │
└─────────────────────────────────────────────────────────┘

Performance Analysis

Clock-Pro complexity:

• Insert: O(1)
• Lookup: O(1)
• Eviction: O(1) amortized

Hit rate improvement over LRU:

• LRU: 90% hit rate (typical)
• Clock-Pro: 95-99% hit rate (adaptive)

I/O reduction:

With 1GB cache, 100GB dataset, 1% access skew:
LRU: 10% miss × 100M accesses = 10M I/O ops
Clock-Pro: 2% miss × 100M accesses = 2M I/O ops (5x reduction)

Structs

CacheStats

Cache statistics

CachedPage

A cached page

ClockProCache

Clock-Pro adaptive page cache

PageId

Unique identifier for a page

Enums

PageState

State of a page in the cache

Constants

DEFAULT_CACHE_PAGES

Default cache capacity in pages

DEFAULT_PAGE_SIZE

Default page size (64KB - optimized for SSTable blocks)

MAX_HOT_RATIO

Maximum hot ring size (fraction of total)

MIN_HOT_RATIO

Minimum hot ring size (fraction of total)