How abiiranathan/gokache works
Project Type and Purpose
• Type: Go library (importable module), not a full service.
• Purpose: Provide a highly concurrent in-memory cache with:
– Sharding (256 internal shards)
– TTL on items
– Background cleanup of expired entries
– Persistence (save/load via gob)
– Graceful shutdown
Main Components
a. Client / Application Code
– Calls Cache API (NewCache, Set, Get, Delete, SaveToDisk, LoadFromDisk, Close)
b. Cache Manager
– The Cache struct that holds configuration, shard array, cleanup ticker, and persistence hooks.
c. Shard Array
– 256 independent shards
– Each shard = a Go map[key]item + sync.RWMutex
– Key hashing → determines target shard
d. In-Memory Item Store
– Each stored value wrapped with metadata: insertion timestamp + TTL
e. Background Cleanup Goroutine
– Ticker based on cleanupInterval
– Iterates shards → locks each shard → purges expired items
f. Persistence Layer
– SaveToDisk: locks all shards → marshals full state via encoding/gob → writes to filesystem
– LoadFromDisk: reads file → decodes gob → repopulates shards
g. Shutdown Handler
– Close() stops cleanup ticker/goroutine and optionally triggers final cleanup
Relationships and Data Flows
• API calls (Set, Get, Delete) → go through Cache Manager → compute shard index → shard lock → read/write map
• Background cleanup ticker → triggers shard sweeps in separate goroutine
• Save/Load operations ↔ filesystem (snapshot file on disk)
• Close() → signals cleanup goroutine to exit + final resource cleanup
Architectural Patterns & Principles
– Sharding for horizontal concurrency (minimizes lock contention)
– Single‐responsibility components: Cache Manager vs. Shards vs. Persistence
– Graceful shutdown & safe concurrency using channels/tickers and sync primitives
– Library pattern: exposes a clean, minimal API surface to host applications