class Sepia::WeakCache(T)

Overview

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

Defined in:

sepia/weak_cache.cr

Constructors

Instance Method Summary

Constructor Detail

def self.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)

[View source]

Instance Method Detail

def cleanup : Int32 #

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"

[View source]
def cleanup_interval : Time::Span #

Interval for automatic cleanup (in seconds)


[View source]
def clear : Void #

Clears all entries from the weak cache.

Example

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

[View source]
def force_cleanup : Void #

Forces cleanup regardless of interval.

Example

weak_cache.force_cleanup

[View source]
def 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

[View source]
def 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

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

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"

[View source]
def live_objects : Array(T) #

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"

[View source]
def memory_pressure : Float64 #

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

[View source]
def memory_usage : Int64 #

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"

[View source]
def needs_cleanup? : Bool #

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

[View source]
def 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)

[View source]
def 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")

[View source]
def stats : 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}

[View source]