safe_memoize 1.1.0 → 1.3.0

data/ROADMAP.md

@@ -4,43 +4,13 @@ This document tracks the planned evolution of SafeMemoize through v1.0.0 and bey
 
 ---
 
-## v1.1.0 — Pluggable Cache Stores
-
-*Goal: allow the in-process hash cache to be swapped for an external store, enabling cross-process and distributed memoization.*
-
-| Feature | Description | Status |
-|---|---|---|
-| Cache store adapter interface | Define a minimal read/write/delete/clear/keys contract that external backends must implement | Shipped |
-| `store:` option on `memoize` | Accept any store adapter object; defaults to the existing in-process hash store | Shipped |
-| Redis adapter | Reference implementation (`SafeMemoize::Stores::Redis`) with TTL, LRU-like expiry, and serialization handled transparently | Shipped |
-| Rails.cache adapter | Thin wrapper around `ActiveSupport::Cache::Store` for projects already using a configured Rails cache | Shipped |
-| Global default store | Set via `SafeMemoize.configure` — applies a default store to every memoized method without per-call configuration | Shipped |
-
----
-
-## v1.2.0 — Async & Fiber-Safe Memoization
-
-*Goal: first-class support for Fiber-based concurrency frameworks (Async, Falcon, Rails async controllers).*
-
-| Feature | Description | Status |
-|---|---|---|
-| Fiber-local memoization mode | `memoize :method, fiber_local: true` stores results in `Fiber[:safe_memoize_cache]` rather than instance variables, giving each fiber its own isolated cache automatically reset when the fiber terminates | Planned |
-| Ractor-compatible shared cache | Revisit `shared: true` using `Ractor::TVar` or shareable frozen objects so class-level caches work across Ractors | Planned |
-| concurrent-ruby integration | Optional adapter using `Concurrent::Map` and `Concurrent::ReentrantReadWriteLock` as a drop-in replacement for `Mutex` where higher read-concurrency is desirable | Planned |
-
----
-
 ## v2.0.0 — Next Generation (Long Horizon)
 
 *Goal: incorporate real-world usage feedback, clean up accumulated API surface, and open a path for advanced extension.*
 
 | Feature | Description | Status |
 |---|---|---|
-| Plugin / extension architecture | A formal `SafeMemoize::Extension` API so third-party gems can add new options, hooks, or store adapters without monkey-patching | Planned |
 | DSL refinements | Evaluate alternative syntax proposals (`memoize_method`, block form, annotation approach) based on community feedback; introduce the preferred form with a migration path from the current API | Planned |
-| Cross-instance cache sharing | Beyond the class-level `shared: true`, support explicitly named shared caches that span unrelated classes | Planned |
-| Cache namespacing | Allow a namespace prefix on all keys for multi-tenant or versioned deployments (especially useful with external stores) | Planned |
-| Automatic cache busting | Optional integration with ActiveRecord's `updated_at` timestamp so object mutations automatically invalidate their own cached entries | Planned |
 
 ---
 

data/Rakefile

@@ -4,12 +4,16 @@ require "bundler/gem_tasks"
 require "rspec/core/rake_task"
 
 RSpec::Core::RakeTask.new(:spec) do |t|
-  # Run store specs first: Ruby Coverage counters for opt-in adapters
-  # (redis, rails_cache) must be exercised before Ractor/concurrency tests
-  # run, which can disrupt coverage tracking in certain Ruby 3.4 builds.
+  # Ordering ensures accurate coverage tracking in Ruby 3.4:
+  # 1. Store specs first: opt-in adapter lines must be hit before Ractor tests
+  #    can disrupt Ruby's Coverage counters.
+  # 2. Ractor specs last: Ractor-based tests spin up background Ractors whose
+  #    internal threads can cause later coverage samples to be missed if they
+  #    interleave with SimpleCov's collection phase.
   store_specs = Dir["spec/stores/**/*_spec.rb"].sort
-  other_specs = Dir["spec/**/*_spec.rb"].sort - store_specs
-  t.rspec_opts = (store_specs + other_specs).join(" ")
+  ractor_specs = Dir["spec/ractor*_spec.rb"].sort
+  other_specs = Dir["spec/**/*_spec.rb"].sort - store_specs - ractor_specs
+  t.rspec_opts = (store_specs + other_specs + ractor_specs).join(" ")
   t.pattern = "non_existent_placeholder" # overridden by rspec_opts file args
 end
 

data/lib/safe_memoize/adapters/concurrent_ruby.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module SafeMemoize
+  module Adapters
+    # Optional store adapter backed by +concurrent-ruby+.
+    #
+    # Replaces the default +Mutex+-guarded +Hash+ with +Concurrent::Map+ and
+    # +Concurrent::ReentrantReadWriteLock+. Multiple readers proceed in parallel;
+    # writers still get exclusive access. For hot paths with many concurrent readers
+    # this can meaningfully reduce lock contention compared to {Stores::Memory}.
+    #
+    # Opt in per class:
+    #
+    #   class MyService
+    #     prepend SafeMemoize
+    #     self.safe_memoize_store = SafeMemoize::Adapters::ConcurrentRuby.new
+    #   end
+    #
+    # Or globally via {SafeMemoize.configure}:
+    #
+    #   SafeMemoize.configure do |c|
+    #     c.default_store = SafeMemoize::Adapters::ConcurrentRuby.new
+    #   end
+    #
+    # Requires the +concurrent-ruby+ gem, which is *not* a runtime dependency of
+    # +safe_memoize+. Add it to your own Gemfile or gemspec:
+    #
+    #   gem "concurrent-ruby"
+    #
+    # A {LoadError} with an actionable message is raised at instantiation time if
+    # the gem is not available.
+    class ConcurrentRuby < Stores::Base
+      def initialize
+        require "concurrent/map"
+        require "concurrent/atomic/reentrant_read_write_lock"
+        @data = Concurrent::Map.new
+        @lock = Concurrent::ReentrantReadWriteLock.new
+      rescue LoadError
+        raise LoadError,
+          "SafeMemoize::Adapters::ConcurrentRuby requires the concurrent-ruby gem. " \
+          "Add `gem 'concurrent-ruby'` to your Gemfile."
+      end
+
+      # @param key [Object]
+      # @return [Object] the stored value, or {MISS} if absent or expired
+      def read(key)
+        @lock.with_read_lock do
+          entry = @data[key]
+          return MISS unless entry
+          return MISS if expired?(entry)
+
+          entry[:value]
+        end
+      end
+
+      # @param key [Object]
+      # @param value [Object]
+      # @param expires_in [Numeric, nil] seconds until expiry; +nil+ means no expiry
+      # @return [void]
+      def write(key, value, expires_in: nil)
+        now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        expires_at = expires_in ? now + expires_in.to_f : nil
+        @lock.with_write_lock do
+          @data[key] = {value: value, expires_at: expires_at, cached_at: now}
+        end
+      end
+
+      # @param key [Object]
+      # @return [void]
+      def delete(key)
+        @lock.with_write_lock { @data.delete(key) }
+      end
+
+      # @return [void]
+      def clear
+        @lock.with_write_lock { @data.clear }
+      end
+
+      # Returns all live (non-expired) keys.
+      # @return [Array<Object>]
+      def keys
+        now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        @lock.with_read_lock do
+          result = []
+          @data.each_pair { |k, entry| result << k unless entry[:expires_at] && entry[:expires_at] <= now }
+          result
+        end
+      end
+
+      private
+
+      def expired?(entry)
+        expires_at = entry[:expires_at]
+        expires_at && expires_at <= Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end

data/lib/safe_memoize/cache_metrics_methods.rb

@@ -9,15 +9,13 @@ module SafeMemoize
       @__safe_memo_metrics__ ||= {}
     end
 
-    def record_cache_hit(method_name, args, kwargs)
-      cache_key = safe_memo_cache_key(method_name, args, kwargs)
+    def record_cache_hit(cache_key)
       metrics = memo_metrics_store
       metrics[cache_key] ||= {hits: 0, misses: 0, total_time: 0.0}
       metrics[cache_key][:hits] += 1
     end
 
-    def record_cache_miss(method_name, args, kwargs, computation_time)
-      cache_key = safe_memo_cache_key(method_name, args, kwargs)
+    def record_cache_miss(cache_key, computation_time)
       metrics = memo_metrics_store
       metrics[cache_key] ||= {hits: 0, misses: 0, total_time: 0.0}
       metrics[cache_key][:misses] += 1
@@ -31,7 +29,8 @@ module SafeMemoize
     def _reset_cache_metrics_for(method_name)
       return unless defined?(@__safe_memo_metrics__) && @__safe_memo_metrics__
 
-      @__safe_memo_metrics__.delete_if { |key, _| key[0] == method_name }
+      effective = resolve_memo_key_name(method_name)
+      @__safe_memo_metrics__.delete_if { |key, _| key[0] == effective }
     end
   end
 end