Sepia::CacheManager
Centralized cache manager for Sepia objects.
Provides thread-safe LRU caching with configurable size limits, TTL, and eviction policies. Designed to work with both regular objects and LazyReference instances.
Example
cache = CacheManager.new(max_size: 1000, ttl: 3600.seconds)
# Store an object
cache.put("doc-123", my_document)
# Retrieve an object
doc = cache.get("doc-123")
# Cache statistics
puts cache.stats
# => {hits: 45, misses: 12, size: 23, max_size: 1000}Constructors
Creates a new cache manager.
Parameters
- max_size : Maximum number of items to cache (default: 1000)
- ttl : Time-to-live for entries (default: nil = no expiration)
Example
cache = CacheManager.new(max_size: 500, ttl: 1.hour)Class methods
Instance methods
Removes all expired entries from the cache.
Returns
The number of expired entries that were removed.
Example
removed = cache.cleanup_expired
puts "Removed #{removed} expired entries"Retrieves an object of specific type from the cache.
Generic version of get that returns the properly typed object.
Parameters
- key : The cache key
Returns
The cached object cast to type T or nil if not found/expired.
Example
doc = cache.get(MyDocument, "doc-123")
puts doc.title if docRetrieves an object from the cache.
Returns nil if the key doesn't exist or the entry has expired.
Updates the access order for LRU tracking.
Parameters
- key : The cache key
Returns
The cached object or nil if not found/expired.
Example
doc = cache.get("doc-123")
puts doc.title if docChecks if a key exists in the cache (excluding expired entries).
Parameters
- key : The cache key
Returns
true if the key exists and hasn't expired, false otherwise.
Example
if cache.has_key?("doc-123")
puts "Document is cached"
endInvalidates a cache entry and updates invalidation statistics.
This is similar to remove, but specifically tracks invalidations (e.g., from external file changes via the filesystem watcher).
Parameters
- key : The cache key to invalidate
Returns
true if the key was invalidated, false if it didn't exist.
Example
cache.invalidate("doc-123") # External file changedReturns an array of all keys currently in the cache.
Returns
Array of cache keys (most recently used last).
Example
keys = cache.keys
puts "Cached objects: #{keys.size}"Estimates memory usage of the cache.
This is a rough estimation based on the number of cached objects. Actual memory usage may vary based on object size.
Returns
Estimated memory usage in bytes.
Example
bytes = cache.memory_usage
puts "Cache uses approximately #{bytes / 1024} KB"Stores an object in the cache.
If the cache is full, implements LRU eviction by removing the least recently used items.
Parameters
- key : The cache key (typically object ID)
- value : The object to cache
Example
cache.put("doc-123", my_document)Removes a specific key from the cache.
Parameters
- key : The cache key to remove
Returns
true if the key was removed, false if it didn't exist.
Example
cache.remove("doc-123")Changes the maximum cache size.
If the new size is smaller than the current cache size, evicts LRU entries to fit the new limit.
Parameters
- new_size : The new maximum cache size
Example
cache.resize(500) # Reduce cache sizeReturns an array of all non-expired values in the cache.
Returns
Array of cached objects.
Example
objects = cache.values
puts "Cached #{objects.size} objects"