safe_memoize 1.1.0 → 1.3.0

data/lib/safe_memoize/fiber_local_methods.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module SafeMemoize
+  # Public and private helpers for fiber-local memoization.
+  #
+  # When a method is memoized with +fiber_local: true+, its cached values are
+  # stored in +Fiber[:__safe_memoize__]+ rather than instance variables, giving
+  # each fiber an isolated cache that is automatically discarded when the fiber
+  # terminates. No mutex is required because fibers are cooperative: only one
+  # fiber runs at a time within a thread.
+  module FiberLocalMethods
+    FIBER_STORE_KEY = :__safe_memoize__
+
+    # Returns +true+ if the given call is currently cached in the current fiber.
+    #
+    # @note In Ruby, +Fiber.new+ inherits the parent fiber's local storage. SafeMemoize
+    #   detects inherited stores via an +:__owner__+ sentinel and creates a fresh
+    #   isolated store for each fiber on first write.
+    #
+    # @param method_name [Symbol, String]
+    # @param args [Array]
+    # @param kwargs [Hash]
+    # @return [Boolean]
+    def fiber_local_memoized?(method_name, *args, **kwargs, &block)
+      return false if block
+
+      method_name = method_name.to_sym
+      cache_key = compute_cache_key(method_name, args, kwargs)
+      record = fiber_memo_cache_or_nil&.[](cache_key)
+      memo_record_live?(record)
+    end
+
+    # Removes one or all fiber-local cached entries for a method in the current fiber.
+    #
+    # @param method_name [Symbol, String]
+    # @param args [Array]
+    # @param kwargs [Hash]
+    # @return [void]
+    def reset_fiber_memo(method_name, *args, **kwargs)
+      method_name = method_name.to_sym
+      cache = fiber_memo_cache_or_nil
+      return unless cache
+
+      if args.empty? && kwargs.empty?
+        effective = resolve_memo_key_name(method_name)
+        cache.delete_if { |key, _| key[0] == effective }
+        fiber_memo_lru_or_nil&.delete(method_name)
+      else
+        cache_key = compute_cache_key(method_name, args, kwargs)
+        cache.delete(cache_key)
+        fiber_memo_lru_or_nil&.[](method_name)&.delete(cache_key)
+      end
+    end
+
+    # Clears all fiber-local cached entries for this instance in the current fiber.
+    #
+    # @return [void]
+    def reset_all_fiber_memos
+      store = Fiber[FIBER_STORE_KEY]
+      return unless store&.[](:__owner__) == Fiber.current.object_id
+
+      store.delete(object_id)
+    end
+
+    private
+
+    # Returns the per-fiber top-level store hash, creating a fresh one for
+    # this fiber if the current store was inherited from a parent fiber.
+    def fiber_root_store!
+      store = Fiber[FIBER_STORE_KEY]
+      unless store&.[](:__owner__) == Fiber.current.object_id
+        store = {__owner__: Fiber.current.object_id}
+        Fiber[FIBER_STORE_KEY] = store
+      end
+      store
+    end
+
+    def fiber_memo_store!
+      fiber_root_store![object_id] ||= {cache: {}, lru: {}}
+    end
+
+    def fiber_memo_cache!
+      fiber_memo_store![:cache]
+    end
+
+    def fiber_memo_lru!
+      fiber_memo_store![:lru]
+    end
+
+    def fiber_root_store_or_nil
+      store = Fiber[FIBER_STORE_KEY]
+      return nil unless store&.[](:__owner__) == Fiber.current.object_id
+
+      store
+    end
+
+    def fiber_memo_store_or_nil
+      fiber_root_store_or_nil&.[](object_id)
+    end
+
+    def fiber_memo_cache_or_nil
+      fiber_memo_store_or_nil&.[](:cache)
+    end
+
+    def fiber_memo_lru_or_nil
+      fiber_memo_store_or_nil&.[](:lru)
+    end
+  end
+end

data/lib/safe_memoize/hooks_methods.rb

@@ -31,7 +31,8 @@ module SafeMemoize
       hooks.each do |hook|
         hook.call(cache_key, record)
       rescue => error
-        handler = SafeMemoize.configuration.on_hook_error
+        # SafeMemoize.configuration is not accessible from non-main Ractors
+        handler = (Ractor.current == Ractor.main) ? SafeMemoize.configuration.on_hook_error : nil
         if handler
           handler.call(error, hook_type, cache_key)
         else
@@ -39,11 +40,17 @@ module SafeMemoize
         end
       end
 
+      # ActiveSupport::Notifications and StatsD integration require main-Ractor
+      # configuration access; skip them from worker Ractors.
+      return if Ractor.current != Ractor.main
+
       safe_memo_notify(hook_type, cache_key) if SafeMemoize.configuration.active_support_notifications
 
       if (client = SafeMemoize.configuration.statsd_client)
         Adapters::StatsD.dispatch(client, hook_type, cache_key, self.class.name)
       end
+
+      SafeMemoize.dispatch_extension_events(hook_type, self.class, safe_memo_bare_method_name(cache_key[0]), cache_key, record)
     end
 
     def safe_memo_notify(hook_type, cache_key)

data/lib/safe_memoize/inspection_methods.rb

@@ -13,7 +13,8 @@ module SafeMemoize
 
     def memo_matcher_for(method_name, args, kwargs)
       if args.empty? && kwargs.empty?
-        ->(key) { key[0] == method_name }
+        effective = resolve_memo_key_name(method_name)
+        ->(key) { key[0] == effective }
       else
         cache_key = compute_cache_key(method_name, args, kwargs)
         ->(key) { key == cache_key }
@@ -28,7 +29,8 @@ module SafeMemoize
       entries = cache.to_a
       return entries unless method_name
 
-      entries.select { |(cache_key, _)| cache_key[0] == method_name }
+      effective = resolve_memo_key_name(method_name)
+      entries.select { |(cache_key, _)| cache_key[0] == effective }
     end
 
     def safe_memo_count_for(method_name)
@@ -57,14 +59,14 @@ module SafeMemoize
       # Custom keys are [method, custom_key] (2 elements); default keys are
       # [method, args, kwargs] (3 elements). Detect and surface accordingly.
       if cache_key.length == 2
-        method_name, custom_key = cache_key
+        effective_name, custom_key = cache_key
         payload = {custom_key: custom_key}
       else
-        method_name, args, kwargs = cache_key
+        effective_name, args, kwargs = cache_key
         payload = {args: args, kwargs: kwargs}
       end
 
-      payload[:method] = method_name if include_method
+      payload[:method] = safe_memo_bare_method_name(effective_name) if include_method
       payload[:value] = memo_record_value(value) if include_value
       payload
     end
@@ -73,6 +75,33 @@ module SafeMemoize
       [method_name.to_sym, deep_freeze_copy(args), deep_freeze_copy(kwargs)]
     end
 
+    # Returns the active namespace string for a bare method name, or nil.
+    # Priority: per-method namespace: option > class safe_memoize_namespace > global.
+    #
+    # Uses instance_variable_get throughout so this is safe to call from worker
+    # Ractors (reads only; lazy-init ivars must not be triggered in that context).
+    def __safe_memo_resolve_namespace__(method_name)
+      ns_map = self.class.instance_variable_get(:@__safe_memo_method_namespaces__)
+      (ns_map && ns_map[method_name]) ||
+        self.class.instance_variable_get(:@__safe_memoize_namespace__) ||
+        SafeMemoize.instance_variable_get(:@configuration)&.namespace
+    end
+
+    # Returns the effective cache key sym for a bare method name, applying any
+    # active namespace (per-method > class-level > global).
+    def resolve_memo_key_name(method_name)
+      ns = __safe_memo_resolve_namespace__(method_name)
+      ns ? :"#{ns}:#{method_name}" : method_name
+    end
+
+    # Strips the namespace prefix from an effective key sym, returning the bare
+    # method name. When no namespace is present the sym is returned unchanged.
+    def safe_memo_bare_method_name(key_sym)
+      s = key_sym.to_s
+      colon_idx = s.index(":")
+      colon_idx ? s[(colon_idx + 1)..].to_sym : key_sym
+    end
+
     def deep_freeze_copy(obj)
       case obj
       when Array

data/lib/safe_memoize/instance_methods.rb

@@ -13,5 +13,6 @@ module SafeMemoize
     include CustomKeyMethods
     include PublicCustomKeyMethods
     include LruMethods
+    include FiberLocalMethods
   end
 end

data/lib/safe_memoize/public_methods.rb

@@ -214,7 +214,8 @@ module SafeMemoize
 
       with_memo_lock do
         cache = memo_cache_or_nil || {}
-        entries = method_name ? cache.select { |key, _| key[0] == method_name } : cache.dup
+        effective = method_name && resolve_memo_key_name(method_name)
+        entries = effective ? cache.select { |key, _| key[0] == effective } : cache.dup
         entries.select! { |_, record| memo_record_live?(record) }
         entries.transform_values { |record| memo_record_value(record) }
       end
@@ -401,7 +402,7 @@ module SafeMemoize
 
         age = (now - record[:cached_at]).round(6) if record[:cached_at]
 
-        metrics_key = safe_memo_cache_key(method_name, args, kwargs)
+        metrics_key = compute_cache_key(method_name, args, kwargs)
         entry_metrics = memo_metrics_store[metrics_key] || {hits: 0, misses: 0}
 
         custom_key = (cache_key.length == 2) ? cache_key[1] : nil

data/lib/safe_memoize/public_metrics_methods.rb

@@ -26,7 +26,8 @@ module SafeMemoize
       method_name = method_name.to_sym
 
       with_memo_lock do
-        metrics = memo_metrics_store.select { |key, _| key[0] == method_name }
+        effective = resolve_memo_key_name(method_name)
+        metrics = memo_metrics_store.select { |key, _| key[0] == effective }
         return empty_stats.merge(method: method_name) if metrics.empty?
 
         aggregate_metrics(metrics, include_method: false).merge(method: method_name)
@@ -73,13 +74,13 @@ module SafeMemoize
       avg_time = total_misses.zero? ? 0.0 : (total_time / total_misses).round(6)
 
       entries = metrics.map do |cache_key, stats|
-        method_name, args, _kwargs = cache_key
+        effective_name, args, _kwargs = cache_key
         entry_calls = stats[:hits] + stats[:misses]
         entry_hit_rate = entry_calls.zero? ? 0.0 : (stats[:hits].to_f / entry_calls * 100).round(2)
 
         entry = {args: args, hits: stats[:hits], misses: stats[:misses],
                  hit_rate: entry_hit_rate, computation_time: stats[:total_time].round(6)}
-        entry[:method] = method_name if include_method
+        entry[:method] = safe_memo_bare_method_name(effective_name) if include_method
         entry
       end
 

data/lib/safe_memoize/ractor_shared_methods.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module SafeMemoize
+  # Class-level methods for Ractor-safe shared caching.
+  #
+  # Mixed into a class (via ClassMethods) when any method is memoized with
+  # +shared: true, ractor_safe: true+. The class owns a supervisor +Ractor+ that
+  # holds the mutable cache hash. All cache reads and writes are serialized through
+  # the supervisor's message loop, removing the need for a +Mutex+ (which is not
+  # Ractor-shareable).
+  #
+  # Constraints for +ractor_safe: true+ memoization:
+  # - Cached return values are made Ractor-shareable via +Ractor.make_shareable+
+  #   (deep-frozen in place). Ensure return values can be frozen.
+  # - +if:+, +unless:+, +max_size:+, +ttl_refresh:+, +key:+, and +store:+ are
+  #   incompatible and raise +ArgumentError+ at +memoize+ time.
+  # - When calling a ractor-safe memoized method from the main Ractor with multiple
+  #   threads, responses are matched by thread identity so concurrent callers do not
+  #   consume each other's replies.
+  module RactorSharedMethods
+    # Clears one or all entries from the Ractor-safe shared cache.
+    #
+    # @param method_name [Symbol, String]
+    # @param args [Array] positional args identifying a specific entry; omit to clear all
+    # @param kwargs [Hash]
+    # @return [void]
+    def reset_ractor_memo(method_name, *args, **kwargs)
+      method_name = method_name.to_sym
+      sup = @__safe_memo_ractor_supervisor__
+      return unless sup
+
+      if args.empty? && kwargs.empty?
+        __ractor_cache_send__(sup, :delete_all, method_name)
+      else
+        key = Ractor.make_shareable([method_name, args.freeze, kwargs.freeze])
+        __ractor_cache_send__(sup, :delete_one, key)
+      end
+    end
+
+    # Clears the entire Ractor-safe shared cache for this class.
+    # @return [void]
+    def reset_all_ractor_memos
+      sup = @__safe_memo_ractor_supervisor__
+      return unless sup
+
+      __ractor_cache_send__(sup, :clear)
+    end
+
+    # Returns +true+ if a live entry exists in the Ractor-safe shared cache.
+    #
+    # @param method_name [Symbol, String]
+    # @param args [Array]
+    # @param kwargs [Hash]
+    # @return [Boolean]
+    def ractor_memoized?(method_name, *args, **kwargs)
+      method_name = method_name.to_sym
+      sup = @__safe_memo_ractor_supervisor__
+      return false unless sup
+
+      key = Ractor.make_shareable([method_name, args.freeze, kwargs.freeze])
+      __ractor_cache_send__(sup, :memoized, key)
+    end
+
+    # Returns the number of live entries in the Ractor-safe shared cache.
+    #
+    # @param method_name [Symbol, String, nil] when given, counts only entries for
+    #   that method; when +nil+, counts all.
+    # @return [Integer]
+    def ractor_memo_count(method_name = nil)
+      sup = @__safe_memo_ractor_supervisor__
+      return 0 unless sup
+
+      __ractor_cache_send__(sup, :count, method_name&.to_sym)
+    end
+
+    private
+
+    # Sends a message to the supervisor and blocks until the tagged response arrives.
+    # Uses Thread.current.object_id as a per-call tag so concurrent threads in the
+    # main Ractor do not steal each other's replies.
+    def __ractor_cache_send__(supervisor, op, *args)
+      tag = Thread.current.object_id
+      msg = Ractor.make_shareable([Ractor.current, tag, op, *args])
+      supervisor.send(msg)
+      Ractor.receive_if { |m| m.is_a?(Array) && m[0] == tag }[1]
+    end
+
+    # Creates the supervisor Ractor that owns this class's Ractor-safe shared cache.
+    # Must be called from the main Ractor at class-definition time.
+    def __safe_memo_ractor_supervisor__
+      # :nocov:
+      @__safe_memo_ractor_supervisor__ ||= Ractor.new do
+        cache = {}
+
+        loop do
+          caller_ractor, tag, op, *args = Ractor.receive
+          now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+          result = case op
+          when :fetch
+            key = args[0]
+            record = cache[key]
+            live = record && (record[:expires_at].nil? || record[:expires_at] > now)
+            live ? {hit: true, record: record} : {hit: false, record: nil}
+
+          when :store
+            key, new_record = args
+            existing = cache[key]
+            live = existing && (existing[:expires_at].nil? || existing[:expires_at] > now)
+            cache[key] = new_record unless live
+            {stored: live ? existing : new_record}
+
+          when :delete_all
+            method_name = args[0]
+            cache.delete_if { |k, _| k[0] == method_name }
+            :ok
+
+          when :delete_one
+            cache.delete(args[0])
+            :ok
+
+          when :clear
+            cache.clear
+            :ok
+
+          when :memoized
+            key = args[0]
+            record = cache[key]
+            !!(record && (record[:expires_at].nil? || record[:expires_at] > now))
+
+          when :count
+            method_name = args[0]
+            cache.count do |k, r|
+              next false if r[:expires_at] && r[:expires_at] <= now
+              method_name.nil? || k[0] == method_name
+            end
+          end
+
+          response = Ractor.make_shareable([tag, result])
+          caller_ractor.send(response)
+        end
+      end
+      # :nocov:
+    end
+  end
+end

data/lib/safe_memoize/release_tooling.rb

@@ -46,6 +46,31 @@ module SafeMemoize
       contents.sub(UNRELEASED_HEADING, "#{UNRELEASED_HEADING}\n\n#{release_heading}")
     end
 
+    # Removes milestone sections from ROADMAP.md where every feature row has
+    # "Shipped" status. Non-milestone sections (Versioning policy, Contributing,
+    # etc.) and sections with any non-Shipped row are left untouched.
+    #
+    # Sections are delimited by the +\n\n---\n\n+ horizontal-rule separator that
+    # the ROADMAP uses between headings. A milestone section is any section whose
+    # first non-blank line starts with +## v+.
+    def prune_roadmap(contents)
+      separator = "\n\n---\n\n"
+      sections = contents.split(separator)
+
+      pruned = sections.reject do |section|
+        next false unless section.lstrip.start_with?("## v")
+
+        # Table rows: lines starting with "|"; drop alignment rows (only |, -, :, whitespace)
+        rows = section.lines.select { |l| l.strip.start_with?("|") }
+        rows = rows.reject { |l| l.match?(/\A[\s|:-]+\z/) }
+        data_rows = rows.drop(1) # first row is the header
+
+        data_rows.any? && data_rows.all? { |row| row.strip.end_with?("Shipped |") }
+      end
+
+      pruned.join(separator)
+    end
+
     def extract_release_notes(contents, version)
       normalized_version = normalize_version(version)
       lines = contents.lines

data/lib/safe_memoize/version.rb

@@ -2,5 +2,5 @@
 
 module SafeMemoize
   # The current gem version string.
-  VERSION = "1.1.0"
+  VERSION = "1.3.0"
 end

data/lib/safe_memoize.rb

@@ -2,10 +2,12 @@
 
 require_relative "safe_memoize/version"
 require_relative "safe_memoize/configuration"
+require_relative "safe_memoize/extension"
 require_relative "safe_memoize/stores/base"
 require_relative "safe_memoize/stores/memory"
 require_relative "safe_memoize/adapters/statsd"
 require_relative "safe_memoize/adapters/opentelemetry"
+require_relative "safe_memoize/adapters/concurrent_ruby"
 require_relative "safe_memoize/class_methods"
 require_relative "safe_memoize/public_methods"
 require_relative "safe_memoize/cache_store_methods"
@@ -17,6 +19,8 @@ require_relative "safe_memoize/public_metrics_methods"
 require_relative "safe_memoize/custom_key_methods"
 require_relative "safe_memoize/public_custom_key_methods"
 require_relative "safe_memoize/lru_methods"
+require_relative "safe_memoize/fiber_local_methods"
+require_relative "safe_memoize/ractor_shared_methods"
 require_relative "safe_memoize/instance_methods"
 
 # Thread-safe memoization for Ruby that correctly handles +nil+ and +false+ values.
@@ -51,6 +55,16 @@ module SafeMemoize
   # Rescue this to catch any error raised by the library itself.
   class Error < StandardError; end
 
+  # @api private
+  SHARED_CACHE_REGISTRY = {}
+  # @api private
+  SHARED_CACHE_MUTEX = Mutex.new
+
+  # @api private
+  EXTENSION_REGISTRY = {}
+  # @api private
+  EXTENSION_MUTEX = Mutex.new
+
   include InstanceMethods
 
   # @api private
@@ -99,4 +113,131 @@ module SafeMemoize
     handler = configuration.on_deprecation
     handler ? handler.call(text) : warn(text)
   end
+
+  # Returns the named shared cache store, creating a new in-process
+  # {Stores::Memory} instance if one has not been registered under +name+.
+  #
+  # Use {register_shared_cache} to supply a custom adapter (e.g. Redis) before
+  # any class that references the same name is loaded.
+  #
+  # @param name [String] the logical cache name
+  # @return [Stores::Base]
+  def self.shared_cache(name)
+    SHARED_CACHE_MUTEX.synchronize do
+      SHARED_CACHE_REGISTRY[name] ||= Stores::Memory.new
+    end
+  end
+
+  # Registers a custom store under +name+, replacing any existing entry.
+  #
+  # Must be called *before* any class that references +name+ via +shared_cache:+
+  # is loaded, because the store is captured at +memoize+ definition time.
+  #
+  # @param name [String] the logical cache name
+  # @param store [Stores::Base] any {Stores::Base} subclass instance
+  # @return [Stores::Base] the registered store
+  # @raise [ArgumentError] if +store+ is not a {Stores::Base} instance
+  def self.register_shared_cache(name, store)
+    unless store.is_a?(Stores::Base)
+      raise ArgumentError, "store must be a SafeMemoize::Stores::Base instance (got #{store.class})"
+    end
+    SHARED_CACHE_MUTEX.synchronize { SHARED_CACHE_REGISTRY[name] = store }
+  end
+
+  # Clears all entries in the named shared cache without removing it from the
+  # registry. A no-op when no cache is registered under +name+.
+  #
+  # @param name [String]
+  # @return [void]
+  def self.clear_shared_cache(name)
+    SHARED_CACHE_MUTEX.synchronize { SHARED_CACHE_REGISTRY[name]&.clear }
+  end
+
+  # Removes the named shared cache from the registry entirely.
+  # Subsequent +shared_cache(name)+ calls will create a fresh store.
+  #
+  # @param name [String]
+  # @return [Stores::Base, nil] the removed store, or +nil+ if not present
+  def self.drop_shared_cache(name)
+    SHARED_CACHE_MUTEX.synchronize { SHARED_CACHE_REGISTRY.delete(name) }
+  end
+
+  # Returns a snapshot of the current registry as a plain +Hash+.
+  #
+  # @return [Hash{String => Stores::Base}]
+  def self.shared_caches
+    SHARED_CACHE_MUTEX.synchronize { SHARED_CACHE_REGISTRY.dup }
+  end
+
+  # Removes all named shared caches from the registry.
+  #
+  # Useful in test suite +after+ hooks to prevent state leaking between examples.
+  #
+  # @return [void]
+  def self.reset_shared_caches!
+    SHARED_CACHE_MUTEX.synchronize { SHARED_CACHE_REGISTRY.clear }
+  end
+
+  # Registers an extension under +name+.
+  #
+  # An extension is any Ruby object that optionally responds to the
+  # {Extension} interface: {Extension#handled_options}, {Extension#process_memoize_option},
+  # and {Extension#dispatch_cache_event}. Use {Extension} as a mixin to get a
+  # convenient DSL for defining these.
+  #
+  # @param name [Symbol, String] a unique identifier for this extension
+  # @param extension [Object] the extension object or module
+  # @return [Object] the registered extension
+  def self.register_extension(name, extension)
+    EXTENSION_MUTEX.synchronize { EXTENSION_REGISTRY[name.to_sym] = extension }
+  end
+
+  # Removes an extension from the registry.
+  #
+  # @param name [Symbol, String]
+  # @return [Object, nil] the removed extension, or +nil+ if not present
+  def self.unregister_extension(name)
+    EXTENSION_MUTEX.synchronize { EXTENSION_REGISTRY.delete(name.to_sym) }
+  end
+
+  # Returns a snapshot of all registered extensions as a +Hash+.
+  #
+  # @return [Hash{Symbol => Object}]
+  def self.extensions
+    EXTENSION_MUTEX.synchronize { EXTENSION_REGISTRY.dup }
+  end
+
+  # Removes all registered extensions.
+  #
+  # Useful in test suite +after+ hooks to prevent state leaking between examples.
+  #
+  # @return [void]
+  def self.reset_extensions!
+    EXTENSION_MUTEX.synchronize { EXTENSION_REGISTRY.clear }
+  end
+
+  # Returns the first registered extension that declares it handles +option_name+,
+  # or +nil+ if none does.
+  #
+  # @param option_name [Symbol]
+  # @return [Object, nil]
+  def self.extension_for_option(option_name)
+    sym = option_name.to_sym
+    EXTENSION_MUTEX.synchronize do
+      EXTENSION_REGISTRY.values.find do |ext|
+        ext.respond_to?(:handled_options) && ext.handled_options.include?(sym)
+      end
+    end
+  end
+
+  # Dispatches a cache lifecycle event to all registered extensions that
+  # respond to +dispatch_cache_event+.
+  #
+  # @api private
+  def self.dispatch_extension_events(event_type, klass, method_name, cache_key, record)
+    exts = EXTENSION_MUTEX.synchronize { EXTENSION_REGISTRY.values.dup }
+    exts.each do |ext|
+      ext.dispatch_cache_event(event_type, klass, method_name, cache_key, record) if ext.respond_to?(:dispatch_cache_event)
+    end
+  end
 end