Class: Ukiryu::Cache

Inherits:
Object
  • Object
show all
Defined in:
lib/ukiryu/cache.rb

Overview

Bounded LRU cache with expiration support

This cache provides:

  • Maximum size limit (evicts oldest entries when limit reached)

  • Time-to-live (TTL) expiration for entries

  • Thread-safe operations

Examples:

cache = Cache.new(max_size: 100, ttl: 300)
cache[:tool] = tool_instance
value = cache[:tool]

Defined Under Namespace

Classes: Entry

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(max_size: 100, ttl: nil, thread_safe: true) ⇒ Cache

Initialize a new cache

Parameters:

  • max_size (Integer) (defaults to: 100) —

    maximum number of entries (default: 100)

  • ttl (Integer, nil) (defaults to: nil) —

    time-to-live in seconds (nil = no expiration)

  • options (Hash) —

    a customizable set of options



45
46
47
48
49
50
51
 
# File 'lib/ukiryu/cache.rb', line 45

def initialize(max_size: 100, ttl: nil, thread_safe: true)
  @max_size = max_size
  @ttl = ttl
  @thread_safe = thread_safe
  @data = {}
  @mutex = Mutex.new if thread_safe
end

Instance Attribute Details

#max_size ⇒ Integer (readonly)

Returns maximum cache size.

Returns:

  • (Integer) —

    maximum cache size



54
55
56
 
# File 'lib/ukiryu/cache.rb', line 54

def max_size
  @max_size
end

#ttl ⇒ Integer? (readonly)

Returns time-to-live in seconds.

Returns:

  • (Integer, nil) —

    time-to-live in seconds



57
58
59
 
# File 'lib/ukiryu/cache.rb', line 57

def ttl
  @ttl
end

Instance Method Details

#[](key) ⇒ Object?

Get a value from the cache

Parameters:

  • key (Object) —

    the cache key

Returns:

  • (Object, nil) —

    the cached value or nil if not found/expired



63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
 
# File 'lib/ukiryu/cache.rb', line 63

def [](key)
  synchronize do
    entry = @data[key]
    return nil unless entry

    # Check expiration
    if entry.expired?(@ttl)
      @data.delete(key)
      return nil
    end

    # Update access time for LRU
    entry.touch!
    entry.value
  end
end

#[]=(key, value) ⇒ Object

Set a value in the cache

Parameters:

  • key (Object) —

    the cache key

  • value (Object) —

    the value to cache

Returns:

  • (Object) —

    the cached value



85
86
87
88
89
90
91
92
93
 
# File 'lib/ukiryu/cache.rb', line 85

def []=(key, value)
  synchronize do
    # Evict oldest entry if at capacity
    evict_if_needed

    @data[key] = Entry.new(value)
    value
  end
end

#clear ⇒ void

This method returns an undefined value.

Clear all entries from the cache



127
128
129
130
131
 
# File 'lib/ukiryu/cache.rb', line 127

def clear
  synchronize do
    @data.clear
  end
end

#delete(key) ⇒ Object?

Delete a key from the cache

Parameters:

  • key (Object) —

    the cache key

Returns:

  • (Object, nil) —

    the deleted value or nil if not found



117
118
119
120
121
122
 
# File 'lib/ukiryu/cache.rb', line 117

def delete(key)
  synchronize do
    entry = @data.delete(key)
    entry&.value
  end
end

#empty? ⇒ Boolean

Check if the cache is empty

Returns:

  • (Boolean) —

    true if cache is empty



143
144
145
 
# File 'lib/ukiryu/cache.rb', line 143

def empty?
  @data.empty?
end

#key?(key) ⇒ Boolean

Check if a key exists in the cache (and is not expired)

Parameters:

  • key (Object) —

    the cache key

Returns:

  • (Boolean) —

    true if key exists and is not expired



99
100
101
102
103
104
105
106
107
108
109
110
111
 
# File 'lib/ukiryu/cache.rb', line 99

def key?(key)
  synchronize do
    entry = @data[key]
    return false unless entry

    if entry.expired?(@ttl)
      @data.delete(key)
      return false
    end

    true
  end
end

#keys ⇒ Array<Object>

Get all keys (excluding expired entries)

Returns:

  • (Array<Object>) —

    array of keys



150
151
152
153
154
155
 
# File 'lib/ukiryu/cache.rb', line 150

def keys
  synchronize do
    cleanup_expired
    @data.keys
  end
end

#size ⇒ Integer

Get the current number of entries

Returns:

  • (Integer) —

    number of entries



136
137
138
 
# File 'lib/ukiryu/cache.rb', line 136

def size
  @data.size
end

#stats ⇒ Hash

Get cache statistics

Returns:

  • (Hash) —

    statistics about the cache



160
161
162
163
164
165
166
167
168
169
170
 
# File 'lib/ukiryu/cache.rb', line 160

def stats
  synchronize do
    cleanup_expired
    {
      size: @data.size,
      max_size: @max_size,
      ttl: @ttl,
      utilization: @data.size.to_f / @max_size
    }
  end
end