Class: Ukiryu::Definition::DefinitionCache

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

Overview

Cache for tool definitions with hot-reload support

This class provides caching for tool definitions with automatic invalidation based on file modification time and TTL.

Defined Under Namespace

Classes: Entry

Constant Summary collapse

DEFAULT_TTL =

Default cache TTL in seconds (5 minutes)

300

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(ttl: DEFAULT_TTL) ⇒ DefinitionCache

Initialize a new cache

Parameters:

  • ttl (Integer) (defaults to: DEFAULT_TTL) —

    default time-to-live in seconds



89
90
91
92
93
94
 
# File 'lib/ukiryu/definition/definition_cache.rb', line 89

def initialize(ttl: DEFAULT_TTL)
  @cache = {}
  @ttl = ttl
  @refresh_strategy = :lazy
  @mutex = Mutex.new
end

Instance Attribute Details

#refresh_strategy ⇒ Symbol

Get the current refresh strategy

Returns:

  • (Symbol) —

    the refresh strategy



198
199
200
 
# File 'lib/ukiryu/definition/definition_cache.rb', line 198

def refresh_strategy
  @refresh_strategy
end

#ttl ⇒ Integer

Get the current TTL

Returns:

  • (Integer) —

    the TTL in seconds



207
208
209
 
# File 'lib/ukiryu/definition/definition_cache.rb', line 207

def ttl
  @ttl
end

Class Method Details

.instance ⇒ DefinitionCache

Get the singleton instance

Returns:



76
77
78
 
# File 'lib/ukiryu/definition/definition_cache.rb', line 76

def instance
  @instance ||= new
end

.reset_instance ⇒ Object

Reset the singleton (useful for testing)



81
82
83
 
# File 'lib/ukiryu/definition/definition_cache.rb', line 81

def reset_instance
  @instance = nil
end

Instance Method Details

#clear ⇒ Integer

Clear all cache entries

Returns:

  • (Integer) —

    number of entries cleared



155
156
157
158
159
160
161
 
# File 'lib/ukiryu/definition/definition_cache.rb', line 155

def clear
  @mutex.synchronize do
    count = @cache.size
    @cache.clear
    count
  end
end

#get(key) ⇒ Models::ToolDefinition?

Get a cached definition

Parameters:

  • key (String) —

    the cache key

Returns:



100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
 
# File 'lib/ukiryu/definition/definition_cache.rb', line 100

def get(key)
  @mutex.synchronize do
    entry = @cache[key]
    return nil unless entry

    # Check staleness
    if entry.stale?(ttl: @ttl)
      if @refresh_strategy == :lazy
        # Refresh and return
        entry = entry.refresh
        @cache[key] = entry if entry
      else
        # Return stale entry (eager mode refreshes in background)
      end
    end
    entry.definition
  end
end

#invalidate(key) ⇒ Boolean

Invalidate a cache entry

Parameters:

  • key (String) —

    the cache key to invalidate

Returns:

  • (Boolean) —

    true if entry was invalidated



146
147
148
149
150
 
# File 'lib/ukiryu/definition/definition_cache.rb', line 146

def invalidate(key)
  @mutex.synchronize do
    !@cache.delete(key).nil?
  end
end

#key?(key) ⇒ Boolean

Check if a key exists in cache

Parameters:

  • key (String) —

    the cache key

Returns:

  • (Boolean) —

    true if key exists



138
139
140
 
# File 'lib/ukiryu/definition/definition_cache.rb', line 138

def key?(key)
  @cache.key?(key)
end

#prune ⇒ Integer

Prune stale entries

Returns:

  • (Integer) —

    number of entries pruned



228
229
230
231
232
233
234
 
# File 'lib/ukiryu/definition/definition_cache.rb', line 228

def prune
  @mutex.synchronize do
    stale_keys = @cache.select { |_, entry| entry.stale?(ttl: @ttl) }.keys
    stale_keys.each { |key| @cache.delete(key) }
    stale_keys.size
  end
end

#refresh_stale ⇒ Integer

Refresh all stale entries

Returns:

  • (Integer) —

    number of entries refreshed



212
213
214
215
216
217
218
219
220
221
222
223
 
# File 'lib/ukiryu/definition/definition_cache.rb', line 212

def refresh_stale
  @mutex.synchronize do
    count = 0
    @cache.each do |key, entry|
      if entry.stale?(ttl: @ttl)
        @cache[key] = entry.refresh
        count += 1
      end
    end
    count
  end
end

#set(key, definition, metadata: nil) ⇒ Models::ToolDefinition

Set a cached definition

Parameters:

Returns:



125
126
127
128
129
130
131
132
 
# File 'lib/ukiryu/definition/definition_cache.rb', line 125

def set(key, definition, metadata: nil)
  @mutex.synchronize do
    mtime = metadata&.mtime
    entry = Entry.new(definition, mtime: mtime)
    @cache[key] = entry
    definition
  end
end

#stale?(key) ⇒ Boolean

Check if a cache entry is stale

Parameters:

  • key (String) —

    the cache key

Returns:

  • (Boolean) —

    true if entry is stale



179
180
181
182
183
184
 
# File 'lib/ukiryu/definition/definition_cache.rb', line 179

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

  entry.stale?(ttl: @ttl)
end

#stats ⇒ Hash

Get cache statistics

Returns:

  • (Hash) —

    cache statistics



166
167
168
169
170
171
172
173
 
# File 'lib/ukiryu/definition/definition_cache.rb', line 166

def stats
  {
    size: @cache.size,
    ttl: @ttl,
    refresh_strategy: @refresh_strategy,
    entries: @cache.keys
  }
end