Class: Kotoshu::Embeddings::LruCache

Inherits:
Object
  • Object
show all
Defined in:
lib/kotoshu/embeddings/lru_cache.rb

Overview

LRU cache for embedding results.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(max_size: 1000, ttl: nil) ⇒ LruCache

Create a new LRU cache

Parameters:

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

    Maximum number of entries (default: 1000)

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

    Time-to-live in seconds (default: nil = no expiry)



37
38
39
40
41
42
43
44
 
# File 'lib/kotoshu/embeddings/lru_cache.rb', line 37

def initialize(max_size: 1000, ttl: nil)
  @max_size = max_size
  @ttl = ttl
  @cache = {}  # key -> {value: v, accessed_at: t, created_at: t}
  @order = []  # Ordered list of keys (most recently used first)
  @hits = 0
  @misses = 0
end

Instance Attribute Details

#hits ⇒ Integer (readonly)

Returns Number of cache hits.

Returns:

  • (Integer) —

    Number of cache hits



27
28
29
 
# File 'lib/kotoshu/embeddings/lru_cache.rb', line 27

def hits
  @hits
end

#max_size ⇒ Integer (readonly)

Returns Maximum number of entries.

Returns:

  • (Integer) —

    Maximum number of entries



21
22
23
 
# File 'lib/kotoshu/embeddings/lru_cache.rb', line 21

def max_size
  @max_size
end

#misses ⇒ Integer (readonly)

Returns Number of cache misses.

Returns:

  • (Integer) —

    Number of cache misses



30
31
32
 
# File 'lib/kotoshu/embeddings/lru_cache.rb', line 30

def misses
  @misses
end

#ttl ⇒ Integer? (readonly)

Returns TTL in seconds.

Returns:

  • (Integer, nil) —

    TTL in seconds



24
25
26
 
# File 'lib/kotoshu/embeddings/lru_cache.rb', line 24

def ttl
  @ttl
end

Instance Method Details

#[](key) ⇒ Object?

Get value for key

Parameters:

  • key (Object) —

    Cache key

Returns:

  • (Object, nil) —

    Cached value or nil if not found/expired



51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
 
# File 'lib/kotoshu/embeddings/lru_cache.rb', line 51

def [](key)
  entry = @cache[key]
  return nil unless entry

  # Check TTL
  if @ttl && (Time.now - entry[:created_at]) > @ttl
    delete(key)
    @misses += 1
    return nil
  end

  # Update access order (move to front = most recently used)
  @order.delete(key)
  @order.unshift(key)
  entry[:accessed_at] = Time.now

  @hits += 1
  entry[:value]
end

#[]=(key, value) ⇒ Object

Set value for key

Parameters:

  • key (Object) —

    Cache key

  • value (Object) —

    Value to cache

Returns:

  • (Object) —

    The value



77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
 
# File 'lib/kotoshu/embeddings/lru_cache.rb', line 77

def []=(key, value)
  # Evict LRU if at capacity
  if @cache.key?(key)
    # Update existing entry
    @cache[key][:value] = value
    @cache[key][:accessed_at] = Time.now
    # Move to front
    @order.delete(key)
    @order.unshift(key)
    return value
  end

  if @cache.size >= @max_size
    evict_lru
  end

  @cache[key] = {
    value: value,
    accessed_at: Time.now,
    created_at: Time.now
  }
  @order.unshift(key)

  value
end

#clear ⇒ self

Clear all entries

Returns:

  • (self) 


135
136
137
138
139
 
# File 'lib/kotoshu/embeddings/lru_cache.rb', line 135

def clear
  @cache.clear
  @order.clear
  self
end

#delete(key) ⇒ Object?

Delete key from cache

Parameters:

  • key (Object) —

    Cache key

Returns:

  • (Object, nil) —

    Deleted value or nil



125
126
127
128
129
 
# File 'lib/kotoshu/embeddings/lru_cache.rb', line 125

def delete(key)
  entry = @cache.delete(key)
  @order.delete(key)
  entry&.[](:value)
end

#empty? ⇒ Boolean

Check if empty

Returns:

  • (Boolean) 


153
154
155
 
# File 'lib/kotoshu/embeddings/lru_cache.rb', line 153

def empty?
  @cache.empty?
end

#fetch(key) {|key| ... } ⇒ Object

Fetch with block (cache-aside pattern)

Yields the key to the block on a miss, matching Ruby's Hash#fetch convention. The block is invoked at most once per call.

Parameters:

  • key (Object) —

    Cache key

Yield Parameters:

  • key (Object) —

    The key being fetched

Yield Returns:

  • (Object) —

    Value to cache and return on miss

Returns:

  • (Object) —

    Cached value or block result



222
223
224
225
226
227
228
229
 
# File 'lib/kotoshu/embeddings/lru_cache.rb', line 222

def fetch(key)
  result = self[key]
  return result if result || key?(key)

  value = yield(key)
  self[key] = value
  value
end

#key?(key) ⇒ Boolean

Check if key exists

Parameters:

  • key (Object) —

    Cache key

Returns:

  • (Boolean) —

    True if key exists and not expired



108
109
110
111
112
113
114
115
116
117
118
 
# File 'lib/kotoshu/embeddings/lru_cache.rb', line 108

def key?(key)
  entry = @cache[key]
  return false unless entry

  if @ttl && (Time.now - entry[:created_at]) > @ttl
    delete(key)
    return false
  end

  true
end

#keys ⇒ Array<Object>

Get all keys

Returns:

  • (Array<Object>) —

    Array of keys



183
184
185
 
# File 'lib/kotoshu/embeddings/lru_cache.rb', line 183

def keys
  @order.dup
end

#lru ⇒ Array<Object, Object>?

Get least recently used key-value pair

Returns:

  • (Array<Object, Object>, nil) 


161
162
163
164
165
166
 
# File 'lib/kotoshu/embeddings/lru_cache.rb', line 161

def lru
  return nil if @order.empty?

  key = @order.last
  [key, @cache[key][:value]]
end

#mru ⇒ Array<Object, Object>?

Get most recently used key-value pair

Returns:

  • (Array<Object, Object>, nil) 


172
173
174
175
176
177
 
# File 'lib/kotoshu/embeddings/lru_cache.rb', line 172

def mru
  return nil if @order.empty?

  key = @order.first
  [key, @cache[key][:value]]
end

#size ⇒ Integer

Get current size

Returns:

  • (Integer) —

    Number of entries



145
146
147
 
# File 'lib/kotoshu/embeddings/lru_cache.rb', line 145

def size
  @cache.size
end

#stats ⇒ Hash

Get cache statistics

Returns:

  • (Hash) —

    Statistics



199
200
201
202
203
204
205
206
207
208
209
 
# File 'lib/kotoshu/embeddings/lru_cache.rb', line 199

def stats
  total = @hits + @misses
  {
    size: size,
    max_size: @max_size,
    hits: @hits,
    misses: @misses,
    hit_rate: total.zero? ? 0.0 : @hits.to_f / total,
    ttl: @ttl
  }
end

#values ⇒ Array<Object>

Get all values

Returns:

  • (Array<Object>) —

    Array of values



191
192
193
 
# File 'lib/kotoshu/embeddings/lru_cache.rb', line 191

def values
  @order.map { |key| @cache[key][:value] }
end