Module: SafeMemoize::ClassMethods
- Defined in:
- lib/safe_memoize/class_methods.rb
Overview
Class-level DSL added to any class that does +prepend SafeMemoize+.
Instance Method Summary collapse
-
#memoize(method_name, ttl: nil, max_size: nil, ttl_refresh: false, if: nil, unless: nil, shared: false, key: nil, store: nil, fiber_local: false, ractor_safe: false) ⇒ void
Wraps an existing instance method with a thread-safe per-instance cache.
-
#memoize_all(except: [], only: [], include_protected: false, include_private: false, **options) ⇒ void
Memoizes every eligible public instance method defined directly on the class.
-
#reset_all_shared_memos ⇒ void
Clears the entire class-level shared cache for this class.
-
#reset_shared_memo(method_name, *args, **kwargs) ⇒ void
Clears one or all entries from the class-level shared cache.
-
#safe_memoize_store ⇒ Stores::Base?
Returns the class-level default cache store, or +nil+ if not set.
-
#safe_memoize_store=(store) ⇒ Stores::Base?
Sets the class-level default cache store.
-
#shared_memo_age(method_name, *args, **kwargs) ⇒ Float?
Returns how many seconds ago the shared entry was cached, or +nil+ if not cached or already expired.
-
#shared_memo_count(method_name = nil) ⇒ Integer
Returns the number of live entries in the class-level shared cache.
-
#shared_memo_stale?(method_name, *args, **kwargs) ⇒ Boolean
Returns +true+ if the shared entry exists but its TTL has elapsed.
-
#shared_memoized?(method_name, *args, **kwargs) ⇒ Boolean
Returns +true+ if a live shared cache entry exists for the given call signature.
Instance Method Details
#memoize(method_name, ttl: nil, max_size: nil, ttl_refresh: false, if: nil, unless: nil, shared: false, key: nil, store: nil, fiber_local: false, ractor_safe: false) ⇒ void
This method returns an undefined value.
Wraps an existing instance method with a thread-safe per-instance cache.
Must be called after the method is defined. Raises +ArgumentError+ immediately at class-definition time if no such method exists.
58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 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 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 |
# File 'lib/safe_memoize/class_methods.rb', line 58 def memoize(method_name, ttl: nil, max_size: nil, ttl_refresh: false, if: nil, unless: nil, shared: false, key: nil, store: nil, fiber_local: false, ractor_safe: false) method_name = method_name.to_sym unless method_defined?(method_name) || private_method_defined?(method_name) || protected_method_defined?(method_name) raise ArgumentError, "cannot memoize :#{method_name} — no instance method with that name is defined on #{self}" end visibility = memoized_method_visibility(method_name) config = SafeMemoize.configuration ttl = config.default_ttl if ttl.nil? max_size = config.default_max_size if max_size.nil? # :if and :unless are reserved Ruby keywords, so they can't be referenced # as local variables directly. binding.local_variable_get is the only way # to read keyword arguments with those names inside the method body. cond_if = binding.local_variable_get(:if) cond_unless = binding.local_variable_get(:unless) ttl = if ttl.nil? nil else ttl = Float(ttl) raise ArgumentError, "ttl must be non-negative" if ttl < 0 ttl end max_size = if max_size.nil? nil else raise ArgumentError, "max_size must be a positive integer" unless max_size.is_a?(Integer) raise ArgumentError, "max_size must be positive" unless max_size > 0 max_size end raise ArgumentError, "ttl_refresh: requires a ttl: to be set" if ttl_refresh && ttl.nil? if cond_if && cond_unless raise ArgumentError, "cannot specify both :if and :unless" end raise ArgumentError, ":if must be callable" if cond_if && !cond_if.respond_to?(:call) raise ArgumentError, ":unless must be callable" if cond_unless && !cond_unless.respond_to?(:call) raise ArgumentError, ":key must be callable" if key && !key.respond_to?(:call) if store raise ArgumentError, "store: must be a SafeMemoize::Stores::Base instance (got #{store.class})" unless store.is_a?(SafeMemoize::Stores::Base) raise ArgumentError, "max_size: is not supported with store: — use the store adapter's own eviction" if max_size raise ArgumentError, "shared: and store: cannot be combined" if shared end if fiber_local raise ArgumentError, "fiber_local: and shared: cannot be combined" if shared raise ArgumentError, "fiber_local: and store: cannot be combined" if store end if ractor_safe raise ArgumentError, "ractor_safe: requires shared: true" unless shared raise ArgumentError, "ractor_safe: is incompatible with if:/unless:" if cond_if || cond_unless raise ArgumentError, "ractor_safe: is incompatible with max_size:" if max_size raise ArgumentError, "ractor_safe: is incompatible with ttl_refresh:" if ttl_refresh raise ArgumentError, "ractor_safe: is incompatible with key:" if key raise ArgumentError, "ractor_safe: is incompatible with store:" if store end # Resolve effective store: per-method store: wins; then class-level # safe_memoize_store; then global default_store. max_size: and shared: # are incompatible with external stores — fall back silently. effective_store = store if effective_store.nil? && !max_size && !shared class_store = safe_memoize_store if class_store effective_store = class_store else global_default = SafeMemoize.configuration.default_store if global_default unless global_default.is_a?(SafeMemoize::Stores::Base) raise ArgumentError, "SafeMemoize.configuration.default_store must be a Stores::Base instance (got #{global_default.class})" end effective_store = global_default end end end __safe_memo_class_key_generators__[method_name] = key if key # Normalize to a single "should cache?" predicate condition = if cond_if cond_if elsif cond_unless ->(result) { !cond_unless.call(result) } end if effective_store miss = SafeMemoize::Stores::Base::MISS mod = Module.new do define_method(method_name) do |*args, **kwargs, &block| return super(*args, **kwargs, &block) if block cache_key = compute_cache_key(method_name, args, kwargs) cached = effective_store.read(cache_key) unless cached.equal?(miss) effective_store.write(cache_key, cached, expires_in: ttl) if ttl_refresh record_cache_hit(method_name, args, kwargs) call_memo_hooks(:on_hit, cache_key, {value: cached, expires_at: nil, cached_at: nil}) return cached end start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC) value = Adapters::OpenTelemetry.trace( SafeMemoize.configuration.opentelemetry_tracer, method_name, self.class.name ) { super(*args, **kwargs) } elapsed_time = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time now = Process.clock_gettime(Process::CLOCK_MONOTONIC) if !condition || condition.call(value) effective_store.write(cache_key, value, expires_in: ttl) call_memo_hooks(:on_store, cache_key, {value: value, expires_at: nil, cached_at: now}) end record_cache_miss(method_name, args, kwargs, elapsed_time) call_memo_hooks(:on_miss, cache_key, {value: value, expires_at: nil, cached_at: now}) value end send(visibility, method_name) end prepend mod return end if fiber_local mod = Module.new do define_method(method_name) do |*args, **kwargs, &block| return super(*args, **kwargs, &block) if block cache_key = compute_cache_key(method_name, args, kwargs) fiber_cache = fiber_memo_cache! record = fiber_cache[cache_key] if memo_record_live?(record) if max_size lru = fiber_memo_lru![method_name] ||= {} lru.delete(cache_key) lru[cache_key] = true end record[:expires_at] = memo_expires_at(ttl) if ttl_refresh record_cache_hit(method_name, args, kwargs) call_memo_hooks(:on_hit, cache_key, record) memo_record_value(record) else call_memo_hooks(:on_expire, cache_key, record) if record start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC) value = Adapters::OpenTelemetry.trace( SafeMemoize.configuration.opentelemetry_tracer, method_name, self.class.name ) { super(*args, **kwargs) } elapsed_time = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time new_record = memo_record(value, expires_at: memo_expires_at(ttl)) if !condition || condition.call(value) if max_size lru = fiber_memo_lru![method_name] ||= {} if lru.size >= max_size evict_key = lru.keys.first lru.delete(evict_key) evicted = fiber_cache.delete(evict_key) call_memo_hooks(:on_evict, evict_key, evicted) if evicted end end fiber_cache[cache_key] = new_record if max_size lru = fiber_memo_lru![method_name] ||= {} lru.delete(cache_key) lru[cache_key] = true end call_memo_hooks(:on_store, cache_key, new_record) end record_cache_miss(method_name, args, kwargs, elapsed_time) call_memo_hooks(:on_miss, cache_key, new_record) value end end send(visibility, method_name) end prepend mod return end if ractor_safe extend(RactorSharedMethods) unless is_a?(RactorSharedMethods) supervisor = __safe_memo_ractor_supervisor__ __memoize_ractor_safe__(method_name, ttl, visibility, supervisor) return end if shared klass = self shared_mutex = klass.send(:__safe_memo_shared_mutex__) mod = Module.new do define_method(method_name) do |*args, **kwargs, &block| return super(*args, **kwargs, &block) if block cache_key = compute_cache_key(method_name, args, kwargs) shared_mutex.synchronize do shared_cache = klass.send(:__safe_memo_shared_cache__) record = shared_cache[cache_key] now = Process.clock_gettime(Process::CLOCK_MONOTONIC) record_live = record && (record[:expires_at].nil? || record[:expires_at] > now) if record_live if max_size lru = klass.send(:__safe_memo_shared_lru_order__)[method_name] ||= {} lru.delete(cache_key) lru[cache_key] = true end record[:expires_at] = memo_expires_at(ttl) if ttl_refresh record_cache_hit(method_name, args, kwargs) call_memo_hooks(:on_hit, cache_key, record) record[:value] else call_memo_hooks(:on_expire, cache_key, record) if record && !record_live start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC) value = Adapters::OpenTelemetry.trace(SafeMemoize.configuration.opentelemetry_tracer, method_name, klass.name) { super(*args, **kwargs) } elapsed_time = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time new_record = memo_record(value, expires_at: memo_expires_at(ttl)) if !condition || condition.call(value) if max_size lru = klass.send(:__safe_memo_shared_lru_order__)[method_name] ||= {} lru.delete_if { |key, _| !shared_cache.key?(key) } if lru.size >= max_size lru_key = lru.keys.first lru.delete(lru_key) evicted = shared_cache.delete(lru_key) call_memo_hooks(:on_evict, lru_key, evicted) if evicted end end shared_cache[cache_key] = new_record if max_size lru = klass.send(:__safe_memo_shared_lru_order__)[method_name] ||= {} lru[cache_key] = true end call_memo_hooks(:on_store, cache_key, new_record) end record_cache_miss(method_name, args, kwargs, elapsed_time) call_memo_hooks(:on_miss, cache_key, new_record) value end end end send(visibility, method_name) end prepend mod return end mod = Module.new do define_method(method_name) do |*args, **kwargs, &block| # Blocks bypass cache entirely — they aren't comparable return super(*args, **kwargs, &block) if block cache_key = compute_cache_key(method_name, args, kwargs) if max_size || condition || ttl_refresh # Locked path: used when LRU tracking, conditional storage, or TTL refresh is needed. memo_mutex!.synchronize do record = memo_cache_record(cache_key) if record lru_touch(method_name, cache_key) if max_size record[:expires_at] = memo_expires_at(ttl) if ttl_refresh record_cache_hit(method_name, args, kwargs) call_memo_hooks(:on_hit, cache_key, record) memo_record_value(record) else start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC) value = Adapters::OpenTelemetry.trace(SafeMemoize.configuration.opentelemetry_tracer, method_name, self.class.name) { super(*args, **kwargs) } elapsed_time = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time new_record = memo_record(value, expires_at: memo_expires_at(ttl)) if !condition || condition.call(value) lru_evict_if_over_limit(method_name, max_size) if max_size @__safe_memo_cache__ ||= {} @__safe_memo_cache__[cache_key] = new_record lru_touch(method_name, cache_key) if max_size call_memo_hooks(:on_store, cache_key, new_record) end record_cache_miss(method_name, args, kwargs, elapsed_time) call_memo_hooks(:on_miss, cache_key, new_record) value end end else # Fast path: check without lock if (record = memo_cache_record(cache_key)) record_cache_hit(method_name, args, kwargs) call_memo_hooks(:on_hit, cache_key, record) return memo_record_value(record) end # Cache miss - compute and store start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC) result = memo_fetch_or_store(cache_key, ttl: ttl) do Adapters::OpenTelemetry.trace(SafeMemoize.configuration.opentelemetry_tracer, method_name, self.class.name) { super(*args, **kwargs) } end elapsed_time = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time with_memo_lock do record_cache_miss(method_name, args, kwargs, elapsed_time) new_record = memo_cache_record(cache_key) call_memo_hooks(:on_store, cache_key, new_record) call_memo_hooks(:on_miss, cache_key, new_record) end result end end send(visibility, method_name) end prepend mod end |
#memoize_all(except: [], only: [], include_protected: false, include_private: false, **options) ⇒ void
This method returns an undefined value.
Memoizes every eligible public instance method defined directly on the class.
Accepts all options that #memoize accepts, plus +:except:+ and +:only:+. Raises +ArgumentError+ when both +:only:+ and +:except:+ are given.
444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 |
# File 'lib/safe_memoize/class_methods.rb', line 444 def memoize_all(except: [], only: [], include_protected: false, include_private: false, **) raise ArgumentError, "cannot specify both :only and :except" if only.any? && except.any? excluded = Array(except).map(&:to_sym) included = Array(only).map(&:to_sym) methods = public_instance_methods(false) methods |= protected_instance_methods(false) if include_protected methods |= private_instance_methods(false) if include_private methods.each do |method_name| next if excluded.include?(method_name) next if included.any? && !included.include?(method_name) memoize(method_name, **) end end |
#reset_all_shared_memos ⇒ void
This method returns an undefined value.
Clears the entire class-level shared cache for this class.
488 489 490 491 492 493 |
# File 'lib/safe_memoize/class_methods.rb', line 488 def reset_all_shared_memos __safe_memo_shared_mutex__.synchronize do @__safe_memo_shared_cache__ = {} @__safe_memo_shared_lru_order__ = {} end end |
#reset_shared_memo(method_name, *args, **kwargs) ⇒ void
This method returns an undefined value.
Clears one or all entries from the class-level shared cache.
With no positional args after +method_name+, clears all shared entries for that method. With args/kwargs, clears only the matching entry.
471 472 473 474 475 476 477 478 479 480 481 482 483 484 |
# File 'lib/safe_memoize/class_methods.rb', line 471 def reset_shared_memo(method_name, *args, **kwargs) method_name = method_name.to_sym specific_key = (args.empty? && kwargs.empty?) ? nil : [method_name, args, kwargs] __safe_memo_shared_mutex__.synchronize do if specific_key __safe_memo_shared_cache__.delete(specific_key) __safe_memo_shared_lru_order__[method_name]&.delete(specific_key) else __safe_memo_shared_cache__.delete_if { |key, _| key[0] == method_name } __safe_memo_shared_lru_order__.delete(method_name) end end end |
#safe_memoize_store ⇒ Stores::Base?
Returns the class-level default cache store, or +nil+ if not set.
Set this to any Stores::Base instance to route every +memoize+ call on this class through that store, without needing to pass +store:+ to each individual +memoize+ call. A per-method +store:+ option still takes precedence, and the global SafeMemoize::Configuration#default_store is the final fallback.
415 416 417 |
# File 'lib/safe_memoize/class_methods.rb', line 415 def safe_memoize_store @__safe_memoize_store__ end |
#safe_memoize_store=(store) ⇒ Stores::Base?
Sets the class-level default cache store.
424 425 426 427 428 429 430 |
# File 'lib/safe_memoize/class_methods.rb', line 424 def safe_memoize_store=(store) if store && !store.is_a?(SafeMemoize::Stores::Base) raise ArgumentError, "safe_memoize_store= must be a SafeMemoize::Stores::Base instance (got #{store.class})" end @__safe_memoize_store__ = store end |
#shared_memo_age(method_name, *args, **kwargs) ⇒ Float?
Returns how many seconds ago the shared entry was cached, or +nil+ if not cached or already expired.
537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 |
# File 'lib/safe_memoize/class_methods.rb', line 537 def shared_memo_age(method_name, *args, **kwargs) method_name = method_name.to_sym cache_key = [method_name, args, kwargs] __safe_memo_shared_mutex__.synchronize do cache = @__safe_memo_shared_cache__ return nil unless cache record = cache[cache_key] return nil unless record now = Process.clock_gettime(Process::CLOCK_MONOTONIC) return nil if record[:expires_at] && record[:expires_at] <= now cached_at = record[:cached_at] return nil unless cached_at (now - cached_at).round(6) end end |
#shared_memo_count(method_name = nil) ⇒ Integer
Returns the number of live entries in the class-level shared cache.
521 522 523 524 525 526 527 528 |
# File 'lib/safe_memoize/class_methods.rb', line 521 def shared_memo_count(method_name = nil) __safe_memo_shared_mutex__.synchronize do cache = @__safe_memo_shared_cache__ || {} now = Process.clock_gettime(Process::CLOCK_MONOTONIC) live = cache.reject { |_, r| r[:expires_at] && r[:expires_at] <= now } method_name ? live.count { |key, _| key[0] == method_name.to_sym } : live.count end end |
#shared_memo_stale?(method_name, *args, **kwargs) ⇒ Boolean
Returns +true+ if the shared entry exists but its TTL has elapsed.
564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 |
# File 'lib/safe_memoize/class_methods.rb', line 564 def shared_memo_stale?(method_name, *args, **kwargs) method_name = method_name.to_sym cache_key = [method_name, args, kwargs] __safe_memo_shared_mutex__.synchronize do cache = @__safe_memo_shared_cache__ return false unless cache record = cache[cache_key] return false unless record expires_at = record[:expires_at] return false unless expires_at expires_at <= Process.clock_gettime(Process::CLOCK_MONOTONIC) end end |
#shared_memoized?(method_name, *args, **kwargs) ⇒ Boolean
Returns +true+ if a live shared cache entry exists for the given call signature.
501 502 503 504 505 506 507 508 509 510 511 512 513 514 |
# File 'lib/safe_memoize/class_methods.rb', line 501 def shared_memoized?(method_name, *args, **kwargs) method_name = method_name.to_sym cache_key = [method_name, args, kwargs] __safe_memo_shared_mutex__.synchronize do cache = @__safe_memo_shared_cache__ return false unless cache record = cache[cache_key] return false unless record record[:expires_at].nil? || record[:expires_at] > Process.clock_gettime(Process::CLOCK_MONOTONIC) end end |