class Sepia::CacheManager

Overview

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}

Defined in:

sepia/cache_manager.cr

Constructors

Class Method Summary

Instance Method Summary

Constructor Detail

def self.instance : CacheManager #

[View source]
def self.new(max_size : Int32 = 1000, ttl : Time::Span | Nil = nil) #

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)

[View source]

Class Method Detail

def self.instance_getter #

Alias for convenience (thread-safe)


[View source]

Instance Method Detail

def cleanup_expired : Int32 #

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"

[View source]
def clear : Void #

Clears all entries from the cache.

Example

cache.clear
puts cache.stats.size # => 0

[View source]
def get(key : String, type : T.class) : T | Nil forall T #

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 doc

[View source]
def get(key : String) : Sepia::Object | Nil #

Retrieves 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 doc

[View source]
def has_key?(key : String) : Bool #

Checks 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"
end

[View source]
def invalidate(key : String) : Bool #

Invalidates 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 changed

[View source]
def keys : Array(String) #

Returns 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}"

[View source]
def max_size : Int32 #

Maximum number of items in cache


[View source]
def memory_usage : Int64 #

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"

[View source]
def put(key : String, value : Sepia::Object) : Void #

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)

[View source]
def remove(key : String) : Bool #

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")

[View source]
def resize(new_size : Int32) : Void #

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 size

[View source]
def stats : Stats #

Current cache statistics


[View source]
def ttl : Time::Span | Nil #

Time-to-live for cache entries (nil = no expiration)


[View source]
def values : Array(Sepia::Object) #

Returns an array of all non-expired values in the cache.

Returns

Array of cached objects.

Example

objects = cache.values
puts "Cached #{objects.size} objects"

[View source]