How erni27/imcache works
Project type and purpose
• imcache is a Go‐based, zero-dependency, generic in-memory cache library intended for embedding in Go applications rather than a standalone service or web app.
• It provides core caching features: expiration (absolute and sliding), eviction policies (LRU, LFU, random), max-entries limits, optional background cleaning, sharding, and eviction callbacks.
File structure
• Top‐level Go source files:
• imcache.go – the main Cache struct and methods
• imcache_test.go – unit tests for Cache
• imcache_benchmark_test.go – performance benchmarks
• cleaner.go – implementation of the background Cleaner
• eviction.go – eviction policy logic and callbacks
• expiration.go – expiration tracking and utilities
• hasher.go – Hasher64 interface and default implementations
• option.go – functional option definitions and parsing
• cleaner.go, eviction.go, expiration.go, hasher.go follow a modular package structure
• go.mod declares dependencies (none external)
• CI, coverage, and linting configs (.github, .codecov.yaml)
README for additional insights
• Explains Cache vs. Sharded, functional options for configuration, and example usage.
• Highlights concurrency safety, shards for parallelism, and extension points (custom Hasher, eviction callback).
Components
a. Core Cache component
• In-memory store (Go map[K]entry[V])
• Mutex lock for concurrency
• Entry metadata: value, expiration timestamp, usage counters (for LFU), last access (for LRU/sliding)
• Methods: Set, Get, Peek, Delete, Clear, Close
b. Sharded Cache
• Composed of N Cache shards
• Hasher64 to map keys → shard index (keyHash % N)
• Exposes same API as Cache but forwards calls to the appropriate shard
c. Cleaner
• Background goroutine per Cache (activated via WithCleanerOption)
• Periodically scans and removes expired entries
d. Eviction subsystem
• Triggered when maxEntries is set or on access
• EvictionPolicy interface: LRU, LFU, Random strategies
• EvictionCallback: user-provided hook invoked asynchronously on evictions
e. Option parsing
• Functional Option pattern (WithExpiration, WithMaxEntriesLimit, etc.)
• Options applied at creation (New or NewSharded) and per-entry (Set)
Relationships and interactions
• User code → calls Cache or Sharded methods
• Cache uses map + mutex internally
• On Set/Get/Delete:
• Check expiration (expiration.go)
• Possibly trigger eviction (eviction.go)
• Invoke eviction callback (eviction.go → user callback)
• Update LRU/LFU metadata
• Cleaner → periodically invokes Cache.purgeExpired()
• Sharded → dispatches each API call to a specific shard based on hasher.go
• Option handling (option.go) → configures Cache/Sharded at construction time
Architectural patterns and design principles
• Functional Options pattern for high configurability without explosion of constructors
• Composition over inheritance: Sharded wraps multiple Cache instances
• Pluggable strategies via interfaces (EvictionPolicy, Hasher64)
• Concurrency safety via per-shard mutexes and goroutine isolation (Cleaner, callback)
• Single responsibility: each .go file focuses on a single concern (expiration, eviction, etc.)
2. Inside Cache<K,V>:
• “expiration.go” and “eviction.go” modules to the map.
6. For Sharded<K,V>:
• Core modules (Cache, Sharded, map): blue
• Concurrency (mutex, Cleaner, callbacks): green
• Extension (options, policies, hasher): orange