class

Sepia::WeakCache(T)

Memory-aware cache using weak references.

This cache holds weak references to objects, allowing the garbage collector to reclaim memory when needed. Automatically cleans up dead references and provides memory pressure monitoring.

Uses Crystal's built-in WeakRef class for proper weak reference behavior.

Example

weak_cache = WeakCache(Sepia::Object).new

# Store an object
weak_cache.put("doc-123", my_document)

# Retrieve an object (may return nil if GC collected it)
doc = weak_cache.get("doc-123")

# Cleanup dead references
weak_cache.cleanup

Constructors

new(cleanup_interval : Time::Span = 60.seconds)

Creates a new weak cache.

Parameters

cleanup_interval : How often to run automatic cleanup (default: 60 seconds)

Example

cache = WeakCache(MyClass).new(cleanup_interval: 30.seconds)

Source

Instance methods

cleanup

Removes all dead references from the weak cache.

This should be called periodically to clean up references to objects that have been garbage collected.

Returns

The number of dead references that were removed.

Example

removed = weak_cache.cleanup
puts "Cleaned up #{removed} dead references"

Source

cleanup_interval

Interval for automatic cleanup (in seconds)

Source

clear

Clears all entries from the weak cache.

Example

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

Source

force_cleanup

Forces cleanup regardless of interval.

Example

weak_cache.force_cleanup

Source

get(key : String) : T | Nil

Retrieves an object from the weak cache.

Returns nil if the key doesn't exist, the object was garbage collected, or the weak reference is dead.

Parameters

key : The cache key

Returns

The cached object or nil.

Example

doc = weak_cache.get("doc-123")
puts doc.title if doc

Source

has_key?(key : String) : Bool

Checks if a key exists in the weak cache.

Parameters

key : The cache key

Returns

true if the key exists and reference is alive, false otherwise.

Example

if weak_cache.has_key?("doc-123")
  puts "Object is cached and alive"
end

Source

live_keys

Returns all live keys in the weak cache.

Returns

Array of keys with alive references.

Example

live_keys = weak_cache.live_keys
puts "#{live_keys.size} objects still cached"

Source

live_objects

Returns all live objects in the weak cache.

Returns

Array of objects with alive references.

Example

live_objects = weak_cache.live_objects
puts "#{live_objects.size} objects still cached"

Source

memory_pressure

Gets the memory pressure level.

Returns a value between 0.0 (no pressure) and 1.0 (high pressure) based on the ratio of dead references to total references.

Returns

Memory pressure level as a float between 0.0 and 1.0.

Example

pressure = weak_cache.memory_pressure
puts "Memory pressure: #{(pressure * 100).round(1)}%"

Source

memory_usage

Estimates memory usage of live objects in the weak cache.

This is a rough estimation based on the number of live objects.

Returns

Estimated memory usage in bytes.

Example

bytes = weak_cache.memory_usage
puts "Weak cache uses approximately #{bytes / 1024} KB"

Source

needs_cleanup?

Checks if cleanup is needed based on interval or pressure.

Returns

true if cleanup is recommended, false otherwise.

Example

if weak_cache.needs_cleanup?
  weak_cache.cleanup
end

Source

put(key : String, object : T) : Void

Stores an object in the weak cache.

The object is stored via weak reference and may be garbage collected if there are no strong references to it elsewhere.

Parameters

key : The cache key
object : The object to cache

Example

weak_cache.put("doc-123", my_document)

Source

remove(key : String) : Bool

Removes a specific key from the weak cache.

Parameters

key : The cache key to remove

Returns

true if the key was removed, false if it didn't exist.

Example

weak_cache.remove("doc-123")

Source

stats

Returns cache statistics including dead reference count.

Returns

Current cache statistics.

Example

puts weak_cache.stats
# => {size: 45, dead_refs: 3, cleanups: 12, total_added: 156}

Source

Nested types

Sepia::WeakCache::Stats