safe_memoize 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 12783636e7ebfd6b21453d9262eb81157d9c82de3a9a538fb8825fd173f072f6
-  data.tar.gz: fff5a502ff49712cf365b3fc67d337ad279f1b28e7ed604ee63b8dcf43e0f6bd
+  metadata.gz: 24faf0555ba5e11e37092aea14e1db090d7f5bb13dd40edc33ea30d8adcba552
+  data.tar.gz: '09beaa5cf9e25284462bdac9636929642213a9e8d657900d30913832da230959'
 SHA512:
-  metadata.gz: 0eedea81071d36fb8891c8767b43b07e5873aaca7d0f14bafdc339acf9c0c040b1e9b050ff72ec840d0edeccf33ef422082423576b5ae58e371dec13f50e4ed0
-  data.tar.gz: 506cadf95e962b1dccf167be9566663ee44d9d4de8ee7eed75bad4189596674b0dc6e485b9063a37f222b1136698b28f031f56d2a035f04e6d3ffa13fcc34b50
+  metadata.gz: 8ed21a58fc95a122794bcb91a1cbccae2bad598b38f736d76eb6f95551245dba070e047eaaea56b26fca6aace181e138acd37a0a027dbb7c0a6a43ae728f2cf0
+  data.tar.gz: f51afd15884dd10c771cd3f3ffcb7d481b0fd3012ecc74148fc9ff82e056abc1a2bb044d5344d635abb5380d200f0ec62a4db528d8fc79697358f775cc4aba3e

data/.github/workflows/ci.yml

@@ -53,12 +53,12 @@ jobs:
           bundler-cache: true
 
       - name: Run test suite
-        run: bundle exec rspec
+        run: bundle exec rake spec
 
       - name: Upload coverage to Codecov
         uses: codecov/codecov-action@v5
         if: matrix.ruby == '3.4'
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
-          files: coverage/.resultset.json
+          files: coverage/coverage.json
 

data/CHANGELOG.md

@@ -8,6 +8,30 @@ from v1.0.0 onwards. Prior 0.x releases may include breaking changes between min
 
 ## [Unreleased]
 
+## [1.2.0] - 2026-05-27
+
+### Added
+
+- `SafeMemoize::Adapters::ConcurrentRuby` — optional store adapter backed by `concurrent-ruby`; uses `Concurrent::Map` as the backing hash and `Concurrent::ReentrantReadWriteLock` to allow multiple readers to proceed in parallel while writers still get exclusive access; reduces lock contention on hot read paths compared to the default `Mutex`-backed `Stores::Memory`; `concurrent-ruby` is a soft dependency — a `LoadError` with an actionable message is raised at instantiation if the gem is not available
+- `.safe_memoize_store=` / `.safe_memoize_store` — class-level attribute for setting a default store on an individual class without touching the global `SafeMemoize.configure` default; takes precedence over `SafeMemoize.configuration.default_store` but is overridden by a per-method `store:` argument; accepts any `SafeMemoize::Stores::Base` instance or `nil`; raises `ArgumentError` for invalid values
+
+- `ractor_safe: true` option on `memoize` — replaces the `Mutex`-backed class-level shared cache with a supervisor `Ractor` that owns the mutable cache hash; all reads and writes are serialised through message passing so the cache is safe to use from multiple Ractors; requires `shared: true`; cached values are deep-frozen via `Ractor.make_shareable`; the memoize wrapper Proc is frozen with `Ractor.make_shareable` before being passed to `define_method` so that classes using `ractor_safe: true` can be passed directly into worker Ractors; incompatible with `if:`, `unless:`, `max_size:`, `ttl_refresh:`, `key:`, and `store:` (raises `ArgumentError`); `ttl:` is supported
+- `.reset_ractor_memo(method_name, *args, **kwargs)` — class method to clear one or all entries from the Ractor-safe shared cache for a given method
+- `.reset_all_ractor_memos` — class method to clear the entire Ractor-safe shared cache for this class
+- `.ractor_memoized?(method_name, *args, **kwargs)` — returns `true` if a live entry exists in the Ractor-safe shared cache for the given call signature
+- `.ractor_memo_count(method_name = nil)` — returns the number of live entries in the Ractor-safe shared cache; scoped to one method when a name is given
+- `fiber_local: true` option on `memoize` — stores results in `Fiber[:__safe_memoize__]` rather than instance variables, giving each fiber its own isolated cache that is automatically discarded when the fiber terminates; no `Mutex` is acquired because fibers are cooperative; a per-fiber ownership sentinel ensures inherited storage from parent fibers is replaced with a fresh isolated store on first write; supports all standard options (`ttl:`, `ttl_refresh:`, `max_size:`, `if:`, `unless:`, `key:`); incompatible with `shared:` and `store:` (raises `ArgumentError`)
+- `#fiber_local_memoized?(method_name, *args, **kwargs)` — returns `true` if the given call is currently cached in the current fiber's store
+- `#reset_fiber_memo(method_name, *args, **kwargs)` — clears one or all fiber-local cached entries for a method in the current fiber
+- `#reset_all_fiber_memos` — clears all fiber-local cached entries for this instance in the current fiber
+
+### Fixed
+
+- `call_memo_hooks` no longer raises `Ractor::IsolationError` when called from a worker Ractor — `SafeMemoize.configuration` (a module-level ivar) is now accessed only from the main Ractor; `ActiveSupport::Notifications` and `StatsD` dispatch are silently skipped from worker Ractors; hook-error handling falls back to `warn` rather than reading the configuration handler
+- CI coverage ordering — ractor specs now run *last* (after all other specs) so that Ractor background threads cannot disrupt Ruby's Coverage counters while collecting coverage for non-Ractor code; previously only store specs were ordered first
+- Codecov reporting accuracy — switched SimpleCov output from `.resultset.json` (internal format, misread by Codecov as ~85%) to `coverage/coverage.json` via `simplecov_json_formatter`; CI now uploads the correct file
+- CI coverage ordering — `bundle exec rspec` ran files alphabetically, causing `ractor_spec.rb` to execute before `spec/stores/`, disrupting Ruby's Coverage counters and dropping reported coverage to ~96%; CI now uses `bundle exec rake spec`, which enforces the store-first ordering already documented in the Rakefile
+
 ## [1.1.0] - 2026-05-22
 
 ### Added
@@ -25,7 +49,7 @@ from v1.0.0 onwards. Prior 0.x releases may include breaking changes between min
 - `store:` type guard in `ClassMethods#memoize` collapsed to an inline guard clause so Ruby's Coverage module counts the raise correctly
 - Hook-error isolation tests (`concurrency_spec`, `hooks_spec`) now configure `on_hook_error = ->(*) {}` to silence expected stderr warnings rather than leaking them into test output; StatsD error-resilience test asserts on the emitted warning with `expect { }.to output(...).to_stderr`
 
-## [1.0.0] - 2026-05-22
+## [1.0.0] - 2026-05-22 
 
 ### Added
 

data/README.md

@@ -67,6 +67,12 @@ SafeMemoize uses Ruby's `prepend` mechanism. When you call `memoize :method_name
 - [`memo_age` and `memo_stale?` for TTL introspection](#cache-inspection)
 - [Class-level `key:` option for shared cache key generation](#custom-cache-keys)
 - [`shared_memo_age` and `shared_memo_stale?` for shared cache TTL inspection](#shared-cache)
+- [Pluggable external cache stores — Redis, Rails.cache, or any custom adapter](#pluggable-cache-stores)
+- [Global default store via `Configuration#default_store`](#pluggable-cache-stores)
+- [`SafeMemoize::Adapters::ConcurrentRuby` — optional `concurrent-ruby` store with parallel-read locking](#concurrent-ruby-adapter)
+- [Class-level `.safe_memoize_store=` — set a per-class default store without touching global config](#class-level-default-store-safe_memoize_store)
+- [Fiber-local memoization via `fiber_local: true` — isolated per-fiber cache, no mutex, works with Async/Falcon](#fiber-local-memoization)
+- [Ractor-safe shared cache via `ractor_safe: true` — supervisor Ractor replaces the Mutex; worker Ractors can call the memoized method directly](#ractor-safe-shared-cache)
 
 ## Installation
 
@@ -498,6 +504,48 @@ Hooks (`on_memo_hit`, `on_memo_miss`, `on_memo_expire`, `on_memo_evict`) fire on
 
 [↑ Back to features](#features)
 
+### Fiber-local memoization
+
+Pass `fiber_local: true` to store results in `Fiber[:__safe_memoize__]` rather than instance variables. Each fiber gets its own isolated cache that is automatically discarded when the fiber terminates — no explicit cleanup required.
+
+This is the right choice for Fiber-based concurrency frameworks like [Async](https://github.com/socketry/async), [Falcon](https://github.com/socketry/falcon), and Rails async controllers, where multiple fibers share the same object instance and must not see each other's cached values.
+
+```ruby
+class ApiClient
+  prepend SafeMemoize
+
+  def fetch(path)
+    http_get(path)
+  end
+
+  memoize :fetch, fiber_local: true
+end
+
+client = ApiClient.new
+
+Fiber.new { client.fetch("/a") }.resume  # computes in this fiber
+Fiber.new { client.fetch("/a") }.resume  # computes again — isolated cache
+```
+
+`fiber_local: true` works with all standard options: `ttl:`, `ttl_refresh:`, `max_size:`, `if:`, `unless:`, and `key:`. It is incompatible with `shared:` and `store:` (both raise `ArgumentError`).
+
+No `Mutex` is acquired because fibers within a single thread are cooperative — only one fiber executes at a time.
+
+**Fiber isolation guarantee**: Ruby's `Fiber.new` inherits the parent fiber's local storage by default. SafeMemoize detects inherited stores via an ownership sentinel and replaces them with a fresh, isolated store on first write, so child fibers never see the parent's cached entries.
+
+Instance-level inspection and reset for fiber-local entries use dedicated methods:
+
+```ruby
+obj.fiber_local_memoized?(:fetch, "/a")  # true / false for the current fiber
+obj.reset_fiber_memo(:fetch)             # clear all entries for :fetch in current fiber
+obj.reset_fiber_memo(:fetch, "/a")       # clear one specific entry
+obj.reset_all_fiber_memos                # clear all fiber-local entries for this instance
+```
+
+Lifecycle hooks and cache metrics work the same as for regular memoization. The existing `memoized?`, `reset_memo`, and `memo_count` methods operate on the instance-variable cache; use the `fiber_local_*` / `reset_fiber_*` API for fiber-local entries.
+
+[↑ Back to features](#features)
+
 ### Bulk memoization
 
 Use `memoize_all` to memoize every public method defined on the class in one call:
@@ -698,7 +746,7 @@ Both settings apply at definition time — methods already memoized before `conf
 SafeMemoize.reset_configuration!
 ```
 
-The configure block also accepts `on_hook_error`, `on_deprecation`, `active_support_notifications`, and `statsd_client` (covered in [Hook error isolation](#hook-error-isolation), [Deprecation](#deprecation), [ActiveSupport::Notifications](#activesupportnotifications), and [StatsD](#statsd)).
+The configure block also accepts `on_hook_error`, `on_deprecation`, `active_support_notifications`, `statsd_client`, and `default_store` (covered in [Hook error isolation](#hook-error-isolation), [Deprecation](#deprecation), [ActiveSupport::Notifications](#activesupportnotifications), [StatsD](#statsd), and [Pluggable cache stores](#pluggable-cache-stores)).
 
 [↑ Back to features](#features)
 
@@ -864,6 +912,155 @@ end
 
 [↑ Back to features](#features)
 
+### Pluggable cache stores
+
+By default, memoized results live in a per-instance hash — fast, but private to each object. Pass `store:` to route reads and writes through any external backend, enabling cross-process and distributed memoization.
+
+#### Built-in: `Stores::Memory`
+
+`Stores::Memory` is the built-in in-process store. It is used automatically by the `store:` default and is the reference implementation for custom adapters. You can pass your own instance to share a cache across multiple classes or to set a TTL on the shared store:
+
+```ruby
+SHARED_STORE = SafeMemoize::Stores::Memory.new
+
+class UserService
+  prepend SafeMemoize
+  def find(id) = User.find(id)
+  memoize :find, store: SHARED_STORE, ttl: 60
+end
+
+class PostService
+  prepend SafeMemoize
+  def author(post) = User.find(post.user_id)
+  memoize :author, store: SHARED_STORE
+end
+```
+
+The store is shared across all instances of a class, so the method is computed only once per unique argument set regardless of how many objects exist.
+
+#### Redis adapter
+
+Requires a Redis-compatible client (the `redis` gem or any drop-in replacement):
+
+```ruby
+require "safe_memoize/stores/redis"
+require "redis"
+
+REDIS_STORE = SafeMemoize::Stores::Redis.new(::Redis.new)
+
+class PricingService
+  prepend SafeMemoize
+  def quote(sku) = api_fetch(sku)
+  memoize :quote, store: REDIS_STORE, ttl: 300
+end
+```
+
+Values and keys are serialized with `Marshal` (Base64-encoded via `Array#pack("m0")`). TTL is forwarded to Redis as `PX` (milliseconds) for sub-second precision. `clear` uses `SCAN` so it never blocks the Redis event loop. All keys are namespace-scoped (default: `"safe_memoize"`) so multiple stores or applications can share one Redis instance:
+
+```ruby
+REDIS_STORE = SafeMemoize::Stores::Redis.new(::Redis.new, namespace: "myapp:memo")
+```
+
+#### Rails.cache adapter
+
+Wraps any `ActiveSupport::Cache::Store`, including `Rails.cache`:
+
+```ruby
+require "safe_memoize/stores/rails_cache"
+
+RAILS_STORE = SafeMemoize::Stores::RailsCache.new(Rails.cache)
+
+class CatalogService
+  prepend SafeMemoize
+  def fetch(slug) = Catalog.find_by!(slug: slug)
+  memoize :fetch, store: RAILS_STORE, ttl: 600
+end
+```
+
+Cached `nil` and `false` values are distinguished from a cache miss via a sentinel envelope, so falsy results are preserved correctly. TTL is forwarded as `expires_in:` for native store expiry. `clear` uses `delete_matched` scoped to the namespace.
+
+#### Custom adapters
+
+Subclass `SafeMemoize::Stores::Base` and implement the six-method contract:
+
+```ruby
+class MyStore < SafeMemoize::Stores::Base
+  def read(key)         = ...  # return MISS if absent
+  def write(key, value, expires_in: nil) = ...
+  def delete(key)       = ...
+  def clear             = ...
+  def keys              = ...  # Array of stored keys
+end
+```
+
+Use `SafeMemoize::Stores::Base::MISS` (a frozen sentinel object) as the return value from `read` when the key is absent — this distinguishes a cache miss from a cached `nil` or `false`.
+
+#### concurrent-ruby adapter
+
+`SafeMemoize::Adapters::ConcurrentRuby` replaces the default `Mutex`-backed store with `Concurrent::Map` and `Concurrent::ReentrantReadWriteLock` from the [`concurrent-ruby`](https://github.com/ruby-concurrency/concurrent-ruby) gem. Multiple readers proceed in parallel; writers still get exclusive access. For read-heavy hot paths this can meaningfully reduce lock contention.
+
+`concurrent-ruby` is a **soft dependency** — it is not required at runtime unless you instantiate the adapter. Add it to your own `Gemfile`:
+
+```ruby
+gem "concurrent-ruby"
+```
+
+Opt in per class:
+
+```ruby
+class HotService
+  prepend SafeMemoize
+  self.safe_memoize_store = SafeMemoize::Adapters::ConcurrentRuby.new
+
+  def expensive(id) = db.find(id)
+  memoize :expensive
+end
+```
+
+Or set it globally:
+
+```ruby
+SafeMemoize.configure do |c|
+  c.default_store = SafeMemoize::Adapters::ConcurrentRuby.new
+end
+```
+
+A `LoadError` with an actionable message is raised at instantiation if `concurrent-ruby` is not installed. The adapter is incompatible with `max_size:` and `shared:` (same constraints as all external stores).
+
+#### Class-level default store (`safe_memoize_store=`)
+
+Set a default store for every `memoize` call on a single class without touching the global configuration:
+
+```ruby
+class ReportService
+  prepend SafeMemoize
+  self.safe_memoize_store = SafeMemoize::Adapters::ConcurrentRuby.new
+
+  def summary = compute_summary   # routed through ConcurrentRuby
+  memoize :summary
+end
+```
+
+The resolution order is: per-method `store:` → class-level `.safe_memoize_store` → global `SafeMemoize.configuration.default_store`. Assign `nil` to clear. An invalid value (not a `Stores::Base` instance) raises `ArgumentError`.
+
+#### Global default store
+
+Set a default store for all compatible `memoize` calls without specifying `store:` on each one:
+
+```ruby
+SafeMemoize.configure do |c|
+  c.default_store = SafeMemoize::Stores::Redis.new(::Redis.new)
+end
+```
+
+A per-method `store:` option always takes precedence. Methods using `max_size:` or `shared:` silently bypass the global default (LRU and shared-mode use their own storage). An invalid value raises `ArgumentError` at `memoize` time. Reset with `SafeMemoize.reset_configuration!`.
+
+#### Compatibility
+
+The `store:` option composes with `ttl:`, `ttl_refresh:`, `if:`, `unless:`, lifecycle hooks, and cache metrics. It is incompatible with `max_size:` (use the store adapter's own eviction) and `shared:` (raise `ArgumentError` if combined).
+
+[↑ Back to features](#features)
+
 ### Deprecation
 
 SafeMemoize ships a structured deprecation helper for gem authors who build on top of it:
@@ -895,17 +1092,72 @@ end
 
 [↑ Back to features](#features)
 
+## Ractor-safe shared cache
+
+Pass `ractor_safe: true` (together with `shared: true`) to replace the `Mutex`-backed class-level shared cache with a supervisor `Ractor` that owns the mutable cache hash. All reads and writes are serialised through message passing, so the cache is safe to use from multiple Ractors.
+
+```ruby
+class PriceService
+  prepend SafeMemoize
+
+  def fetch_price(item_id)
+    external_api.get("/prices/#{item_id}")
+  end
+
+  memoize :fetch_price, shared: true, ractor_safe: true, ttl: 300
+end
+
+# Main Ractor — multiple threads share one cache entry
+20.times.map { Thread.new { PriceService.new.fetch_price(42) } }.map(&:value)
+
+# Worker Ractors also read from and write to the same supervisor cache
+result = Ractor.new(PriceService) { |s| s.new.fetch_price(42) }.take
+```
+
+### How it works
+
+- A **supervisor `Ractor`** is created once per class the first time a `ractor_safe: true` method is memoized. It owns a plain Ruby `Hash` and responds to `:fetch`, `:store`, `:delete_all`, `:delete_one`, `:clear`, `:memoized`, and `:count` messages.
+- The memoize **wrapper Proc** is frozen via `Ractor.make_shareable` before being registered with `define_method`, so the class can be passed directly into `Ractor.new` blocks.
+- Cached values are deep-frozen via `Ractor.make_shareable`. Values that cannot be made shareable (e.g. a `Mutex`) raise `ArgumentError`.
+- **Thread safety** inside the main Ractor (multiple threads) is handled by per-call tags (`Thread.current.object_id`) combined with `Ractor.receive_if`, so concurrent threads never consume each other's replies.
+- `ttl:` is supported. Expired entries are skipped by the supervisor's `:fetch` handler.
+
+### Constraints
+
+`ractor_safe: true` is intentionally limited. The following options are incompatible and raise `ArgumentError` at `memoize` time:
+
+| Option | Reason |
+|---|---|
+| `if:` / `unless:` | Conditional Procs are non-Ractor-shareable |
+| `max_size:` | LRU order tracking requires a non-shareable Ruby `Hash` |
+| `ttl_refresh:` | Requires re-examining the record on every hit |
+| `key:` | Custom key Procs are non-Ractor-shareable |
+| `store:` | External adapters are incompatible with the supervisor model |
+
+### Class-level API
+
+```ruby
+PriceService.ractor_memoized?(:fetch_price, 42)     # → true / false
+PriceService.ractor_memo_count                       # → total live entries
+PriceService.ractor_memo_count(:fetch_price)         # → entries for one method
+PriceService.reset_ractor_memo(:fetch_price, 42)     # → clear one entry
+PriceService.reset_ractor_memo(:fetch_price)         # → clear all entries for method
+PriceService.reset_all_ractor_memos                  # → clear entire shared cache
+```
+
+[↑ Back to features](#features)
+
 ## Ractor compatibility
 
-SafeMemoize is **not Ractor-compatible** in its current form. Passing a class that uses `memoize` into a `Ractor.new` block raises `RuntimeError: defined with an un-shareable Proc in a different Ractor`. There are two root causes:
+Regular `memoize` (without `ractor_safe: true`) is **not Ractor-compatible**. Passing a class that uses `memoize` into a `Ractor.new` block raises `RuntimeError: defined with an un-shareable Proc in a different Ractor`. There are two root causes:
 
 1. **Non-shareable closures.** `ClassMethods#memoize` builds anonymous modules using `define_method` with blocks that close over local variables (`ttl`, `max_size`, `condition`, `shared_mutex`, …). Ruby marks those Procs as non-Ractor-shareable, so the host class cannot be sent to a Ractor.
 
-2. **Mutable module-level state.** `SafeMemoize.configuration` reads `@configuration` from the `SafeMemoize` module — a mutable ivar on a shared constant — which raises `Ractor::IsolationError` from a non-main Ractor. This affects every memoized call because hooks and adapters always read the configuration.
+2. **Mutable module-level state.** `SafeMemoize.configuration` reads `@configuration` from the `SafeMemoize` module — a mutable ivar on a shared constant — which raises `Ractor::IsolationError` from a non-main Ractor.
 
-**Workaround:** Use Ruby Threads instead of Ractors — SafeMemoize is fully thread-safe via double-check locking and per-instance Mutexes. If you need true parallelism with Ractors, perform computation inside the Ractor without memoization and send frozen results back via `Ractor#send`.
+**Workaround for shared caches:** use `memoize :method, shared: true, ractor_safe: true` (see [Ractor-safe shared cache](#ractor-safe-shared-cache) above).
 
-Ractor support is tracked in the v1.0.0 roadmap. The fix would require replacing closed-over variables with frozen shareable bindings and making `Configuration` a frozen value object, which is a significant redesign.
+**Workaround for per-instance caches:** Use Ruby Threads instead of Ractors — SafeMemoize is fully thread-safe via double-check locking and per-instance Mutexes. If you need true parallelism with Ractors, perform computation inside the Ractor without memoization and send frozen results back via `Ractor#send`.
 
 ## Development
 
@@ -982,6 +1234,9 @@ Anything **not** listed here — internal modules, private methods, `@__safe_mem
 | `unless:` | `Symbol \| Proc \| nil` | `nil` | Store only when falsy |
 | `shared:` | `Boolean` | `false` | Class-level shared cache |
 | `key:` | `Proc \| nil` | `nil` | Class-level custom key generator |
+| `store:` | `Stores::Base \| nil` | `nil` | External cache store adapter; incompatible with `max_size:` and `shared:` |
+| `fiber_local:` | `Boolean` | `false` | Fiber-local cache; each fiber gets an isolated store; incompatible with `shared:` and `store:` |
+| `ractor_safe:` | `Boolean` | `false` | Supervisor-Ractor shared cache; replaces the `Mutex`; worker Ractors can call the method; requires `shared: true`; cached values are deep-frozen; incompatible with `if:`, `unless:`, `max_size:`, `ttl_refresh:`, `key:`, and `store:` |
 
 ### `memoize_all` options (class method)
 
@@ -1055,6 +1310,14 @@ All `memoize` option keys above, plus:
 | `memoize_with_custom_key(method_name) { \|*args, **kwargs\| … }` | Instance-level key generator |
 | `clear_custom_keys(method_name = nil)` | Remove one or all key generators |
 
+**Fiber-local cache (when any method uses `fiber_local: true`)**
+
+| Method | Returns |
+|---|---|
+| `fiber_local_memoized?(method_name, *args, **kwargs)` | `Boolean` — cached in the current fiber? |
+| `reset_fiber_memo(method_name, *args, **kwargs)` | `nil` — clear one or all entries in current fiber |
+| `reset_all_fiber_memos` | `nil` — clear all fiber-local entries for this instance |
+
 ### Shared-cache class methods (added when any method uses `shared: true`)
 
 | Method | Returns |
@@ -1066,6 +1329,15 @@ All `memoize` option keys above, plus:
 | `shared_memo_age(method_name, *args, **kwargs)` | `Numeric \| nil` |
 | `shared_memo_stale?(method_name, *args, **kwargs)` | `Boolean` |
 
+**Ractor-safe shared cache (added when any method uses `ractor_safe: true`)**
+
+| Method | Returns |
+|---|---|
+| `reset_ractor_memo(method_name, *args, **kwargs)` | `nil` — clear one or all entries |
+| `reset_all_ractor_memos` | `nil` — clear the entire Ractor-safe shared cache |
+| `ractor_memoized?(method_name, *args, **kwargs)` | `Boolean` — live entry exists? |
+| `ractor_memo_count(method_name = nil)` | `Integer` — live entry count |
+
 ### `SafeMemoize::Configuration` attributes
 
 | Attribute | Type | Default |
@@ -1077,10 +1349,20 @@ All `memoize` option keys above, plus:
 | `active_support_notifications` | `Boolean` | `false` |
 | `statsd_client` | `Object \| nil` | `nil` |
 | `opentelemetry_tracer` | `Object \| nil` | `nil` |
+| `default_store` | `Stores::Base \| nil` | `nil` |
+
+### Store adapter classes (v1.1.0+)
+
+| Class | Require | Notes |
+|---|---|---|
+| `SafeMemoize::Stores::Base` | auto | Abstract base — subclass to build custom adapters; exposes `MISS` sentinel |
+| `SafeMemoize::Stores::Memory` | auto | Built-in in-process store; reference implementation |
+| `SafeMemoize::Stores::Redis` | `"safe_memoize/stores/redis"` | Redis-backed adapter; Marshal serialization; `PX` TTL |
+| `SafeMemoize::Stores::RailsCache` | `"safe_memoize/stores/rails_cache"` | `ActiveSupport::Cache::Store` wrapper |
 
 ### Opt-in extensions (not guaranteed until their owning milestone ships)
 
-The following are available now but reside under `require "safe_memoize/rails"` and are not covered by the v1.0.0 semver guarantee until the v1.x milestone that owns them is declared stable:
+The following are available now but reside under `require "safe_memoize/rails"` and are not covered by the semver guarantee until the v1.x milestone that owns them is declared stable:
 
 - `SafeMemoize::Rails` module (`track`, `reset_tracked!`)
 - `SafeMemoize::Rails::RequestScoped` concern

data/ROADMAP.md

@@ -4,32 +4,6 @@ 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.*

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/class_methods.rb

@@ -29,6 +29,15 @@ module SafeMemoize
     #   {Stores::Base} subclass instance. The store is shared across all instances of the
     #   class. When +nil+, the default per-instance in-process hash is used.
     #   Cannot be combined with +max_size:+ or +shared:+.
+    # @param fiber_local [Boolean] when +true+, results are stored in
+    #   +Fiber[:__safe_memoize__]+ rather than instance variables. Each fiber gets its
+    #   own isolated cache that is automatically discarded when the fiber terminates. No
+    #   mutex is acquired. Cannot be combined with +shared:+ or +store:+.
+    # @param ractor_safe [Boolean] when +true+, the class-level shared cache is owned by
+    #   a supervisor +Ractor+ rather than a +Mutex+-protected ivar, making it accessible
+    #   from worker Ractors. Requires +shared: true+. Cached values are deep-frozen via
+    #   +Ractor.make_shareable+. Incompatible with +if:+, +unless:+, +max_size:+,
+    #   +ttl_refresh:+, +key:+, and +store:+.
     # @return [void]
     # @raise [ArgumentError] if the method does not exist, or option values are invalid
     #
@@ -46,7 +55,7 @@ module SafeMemoize
     # @example With a custom store
     #   STORE = SafeMemoize::Stores::Memory.new
     #   memoize :fetch, store: STORE, ttl: 300
-    def memoize(method_name, ttl: nil, max_size: nil, ttl_refresh: false, if: nil, unless: nil, shared: false, key: nil, store: nil)
+    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)
@@ -99,17 +108,37 @@ module SafeMemoize
         raise ArgumentError, "shared: and store: cannot be combined" if shared
       end
 
-      # Resolve effective store: explicit store: wins; global default applies when
-      # compatible (max_size: and shared: are incompatible — fall back silently).
+      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
-        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})"
+        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
-          effective_store = global_default
         end
       end
 
@@ -165,6 +194,77 @@ module SafeMemoize
         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__)
@@ -303,6 +403,32 @@ module SafeMemoize
       prepend mod
     end
 
+    # 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.
+    #
+    # @return [Stores::Base, nil]
+    def safe_memoize_store
+      @__safe_memoize_store__
+    end
+
+    # Sets the class-level default cache store.
+    #
+    # @param store [Stores::Base, nil] a store instance, or +nil+ to clear
+    # @return [Stores::Base, nil]
+    # @raise [ArgumentError] if +store+ is not a {Stores::Base} instance (and not +nil+)
+    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
+
     # Memoizes every eligible public instance method defined directly on the class.
     #
     # Accepts all options that {#memoize} accepts, plus +:except:+ and +:only:+.
@@ -477,5 +603,67 @@ module SafeMemoize
 
       :public
     end
+
+    # Builds and prepends the ractor_safe memoize wrapper in its own method so
+    # the Proc only closes over the four Ractor-shareable locals (method_name,
+    # ttl, visibility, supervisor) rather than the full memoize binding, which
+    # contains non-shareable objects like SafeMemoize.configuration.
+    #
+    # The Proc is created inside module_eval so its self is the anonymous
+    # module (a shareable object), then frozen via Ractor.make_shareable before
+    # being passed to define_method. Without that step, ANY define_method Proc
+    # is considered non-shareable by Ruby 3.x even when it captures nothing.
+    def __memoize_ractor_safe__(method_name, ttl, visibility, supervisor)
+      mod = Module.new
+      wrapper = mod.module_eval do
+        Ractor.make_shareable(
+          proc do |*args, **kwargs, &block|
+            return super(*args, **kwargs, &block) if block
+
+            cache_key = Ractor.make_shareable([method_name, deep_freeze_copy(args), deep_freeze_copy(kwargs)])
+
+            tag = Thread.current.object_id
+            supervisor.send(Ractor.make_shareable([Ractor.current, tag, :fetch, cache_key]))
+            response = Ractor.receive_if { |m| m.is_a?(Array) && m[0] == tag }[1]
+
+            if response[:hit]
+              record_cache_hit(method_name, args, kwargs)
+              call_memo_hooks(:on_hit, cache_key, response[:record])
+              return response[:record][:value]
+            end
+
+            start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            value = super(*args, **kwargs)
+            elapsed_time = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
+
+            begin
+              shareable_value = Ractor.make_shareable(value)
+            rescue => e
+              raise ArgumentError, "ractor_safe: memoized values must be Ractor-shareable (#{e.message})"
+            end
+
+            now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            record = Ractor.make_shareable({
+              value: shareable_value,
+              expires_at: ttl ? now + ttl : nil,
+              cached_at: now
+            })
+
+            supervisor.send(Ractor.make_shareable([Ractor.current, tag, :store, cache_key, record]))
+            stored = Ractor.receive_if { |m| m.is_a?(Array) && m[0] == tag }[1]
+            stored_record = stored[:stored]
+
+            record_cache_miss(method_name, args, kwargs, elapsed_time)
+            call_memo_hooks(:on_store, cache_key, stored_record)
+            call_memo_hooks(:on_miss, cache_key, stored_record)
+
+            stored_record[:value]
+          end
+        )
+      end
+      mod.define_method(method_name, wrapper)
+      mod.send(visibility, method_name)
+      prepend mod
+    end
   end
 end

data/lib/safe_memoize/fiber_local_methods.rb

@@ -0,0 +1,108 @@
+# 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?
+        cache.delete_if { |key, _| key[0] == method_name }
+        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,6 +40,10 @@ 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)

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/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.2.0"
 end

data/lib/safe_memoize.rb

@@ -6,6 +6,7 @@ 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 +18,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.

data/sig/safe_memoize.rbs

@@ -38,8 +38,10 @@ module SafeMemoize
   end
 
   module ClassMethods
-    def memoize: (Symbol | String method_name, ?ttl: Numeric?, ?max_size: Integer?, ?ttl_refresh: bool, ?if: (^(untyped result) -> boolish)?, ?unless: (^(untyped result) -> boolish)?, ?shared: bool, ?key: (^(*untyped args, **untyped kwargs) -> untyped)?, ?store: Stores::Base?) -> void
-    def memoize_all: (?except: Array[Symbol | String], ?only: Array[Symbol | String], ?include_protected: bool, ?include_private: bool, ?ttl: Numeric?, ?max_size: Integer?, ?if: (^(untyped result) -> boolish)?, ?unless: (^(untyped result) -> boolish)?, ?shared: bool, ?key: (^(*untyped args, **untyped kwargs) -> untyped)?) -> void
+    def memoize: (Symbol | String method_name, ?ttl: Numeric?, ?max_size: Integer?, ?ttl_refresh: bool, ?if: (^(untyped result) -> boolish)?, ?unless: (^(untyped result) -> boolish)?, ?shared: bool, ?key: (^(*untyped args, **untyped kwargs) -> untyped)?, ?store: Stores::Base?, ?fiber_local: bool, ?ractor_safe: bool) -> void
+    def safe_memoize_store: () -> Stores::Base?
+    def safe_memoize_store=: (Stores::Base?) -> Stores::Base?
+    def memoize_all: (?except: Array[Symbol | String], ?only: Array[Symbol | String], ?include_protected: bool, ?include_private: bool, ?ttl: Numeric?, ?max_size: Integer?, ?if: (^(untyped result) -> boolish)?, ?unless: (^(untyped result) -> boolish)?, ?shared: bool, ?key: (^(*untyped args, **untyped kwargs) -> untyped)?, ?fiber_local: bool) -> void
     def reset_shared_memo: (Symbol | String method_name, *untyped args, **untyped kwargs) -> void
     def reset_all_shared_memos: () -> void
     def shared_memoized?: (Symbol | String method_name, *untyped args, **untyped kwargs) -> bool
@@ -187,6 +189,37 @@ module SafeMemoize
     def lru_clear_all: () -> void
   end
 
+  module FiberLocalMethods
+    FIBER_STORE_KEY: Symbol
+
+    def fiber_local_memoized?: (Symbol | String method_name, *untyped args, **untyped kwargs) ?{ () -> untyped } -> bool
+    def reset_fiber_memo: (Symbol | String method_name, *untyped args, **untyped kwargs) -> void
+    def reset_all_fiber_memos: () -> void
+
+    private
+
+    def fiber_root_store!: () -> Hash[untyped, untyped]
+    def fiber_memo_store!: () -> { cache: Hash[memo_key, memo_record], lru: Hash[Symbol, Hash[memo_key, true]] }
+    def fiber_memo_cache!: () -> Hash[memo_key, memo_record]
+    def fiber_memo_lru!: () -> Hash[Symbol, Hash[memo_key, true]]
+    def fiber_root_store_or_nil: () -> Hash[untyped, untyped]?
+    def fiber_memo_store_or_nil: () -> { cache: Hash[memo_key, memo_record], lru: Hash[Symbol, Hash[memo_key, true]] }?
+    def fiber_memo_cache_or_nil: () -> Hash[memo_key, memo_record]?
+    def fiber_memo_lru_or_nil: () -> Hash[Symbol, Hash[memo_key, true]]?
+  end
+
+  module RactorSharedMethods
+    def reset_ractor_memo: (Symbol | String method_name, *untyped args, **untyped kwargs) -> void
+    def reset_all_ractor_memos: () -> void
+    def ractor_memoized?: (Symbol | String method_name, *untyped args, **untyped kwargs) -> bool
+    def ractor_memo_count: (?(Symbol | String) method_name) -> Integer
+
+    private
+
+    def __ractor_cache_send__: (untyped supervisor, Symbol op, *untyped args) -> untyped
+    def __safe_memo_ractor_supervisor__: () -> untyped
+  end
+
   module InstanceMethods
     include PublicMethods
     include CacheStoreMethods
@@ -198,6 +231,7 @@ module SafeMemoize
     include CustomKeyMethods
     include PublicCustomKeyMethods
     include LruMethods
+    include FiberLocalMethods
   end
 
   module Stores
@@ -237,6 +271,17 @@ module SafeMemoize
       SPAN_NAME: String
       def self.trace: (untyped tracer, Symbol | String method_name, String? class_name) { () -> untyped } -> untyped
     end
+
+    class ConcurrentRuby < Stores::Base
+      def initialize: () -> void
+      def read: (untyped key) -> untyped
+      def write: (untyped key, untyped value, ?expires_in: Numeric?) -> void
+      def delete: (untyped key) -> void
+      def clear: () -> void
+      def keys: () -> Array[untyped]
+      private
+      def expired?: ({ expires_at: Float?, value: untyped, cached_at: Float }) -> bool
+    end
   end
 
   module Rails

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: safe_memoize
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Chuck Smith
@@ -52,6 +52,7 @@ files:
 - benchmarks/benchmark.rb
 - codecov.yml
 - lib/safe_memoize.rb
+- lib/safe_memoize/adapters/concurrent_ruby.rb
 - lib/safe_memoize/adapters/opentelemetry.rb
 - lib/safe_memoize/adapters/statsd.rb
 - lib/safe_memoize/cache_metrics_methods.rb
@@ -60,6 +61,7 @@ files:
 - lib/safe_memoize/class_methods.rb
 - lib/safe_memoize/configuration.rb
 - lib/safe_memoize/custom_key_methods.rb
+- lib/safe_memoize/fiber_local_methods.rb
 - lib/safe_memoize/hooks_methods.rb
 - lib/safe_memoize/inspection_methods.rb
 - lib/safe_memoize/instance_methods.rb
@@ -67,6 +69,7 @@ files:
 - lib/safe_memoize/public_custom_key_methods.rb
 - lib/safe_memoize/public_methods.rb
 - lib/safe_memoize/public_metrics_methods.rb
+- lib/safe_memoize/ractor_shared_methods.rb
 - lib/safe_memoize/rails.rb
 - lib/safe_memoize/rails/middleware.rb
 - lib/safe_memoize/rails/request_scoped.rb