safe_memoize 1.7.0 → 1.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e7a646739aa7f6c178b20192ddc8e94768df0c6b000097586796153f5d2138bc
-  data.tar.gz: 9454f9a6cf6b8e420d27b82f39740484eddab506d871e94034483ae8caf12622
+  metadata.gz: 0b2558ad027e3b8bb09ec956d8a18eed759b56c9baa1234a173fdebd7e5e9913
+  data.tar.gz: ae5302c29efe49c336a323bc7a6ad8dcd4a6b10cebc394e786fccd12c00a66ab
 SHA512:
-  metadata.gz: f569af43ba1ca765dcdd9490f5629bb572f1dbedaa676538a08c199282fe55a6b40afd29f8870ddbab86c091a20a89c10e87c3b060a124f4994313b2a2ffdda4
-  data.tar.gz: 2d0634278dd32e98fc0c23a74abfb98bf1c8d5d087e7eb7a8006dd54846bd11f0bbce27d704e4f82bf0fc81c961c34b1c62fb8dc92cddafbcec26c2b930e79d8
+  metadata.gz: 5822061de749e6001cee636a687c19bfd59253ed075b4d9e82123aa88954578a3a8f2dcd0a5a9cbfb29cad8d86b6768a5461a454210dfd7bf56ba624e4e6df6c
+  data.tar.gz: 89e21d16cb9e37a00333f98ec12adf7b9ec6a3e746bb1a9f8377cfafd16c27abbd92de5a79074e207f51fcacaa25a0e9c58092da94a82798be501d35a677489c

data/.github/workflows/ci.yml

@@ -34,6 +34,9 @@ jobs:
   test:
     name: Ruby ${{ matrix.ruby }}
     runs-on: ubuntu-latest
+    # Normal runs finish in under a minute; fail fast if the suite hangs
+    # (default is 6 hours).
+    timeout-minutes: 10
     strategy:
       fail-fast: false
       matrix:
@@ -55,6 +58,12 @@ jobs:
       - name: Run test suite
         run: bundle exec rake spec
 
+      # SimpleCov marks :nocov: lines as "ignored"; Codecov rejects non-numeric
+      # line values and discards the whole report, so treat them as non-lines.
+      - name: Normalize ignored lines for Codecov
+        if: matrix.ruby == '3.4'
+        run: sed -i 's/"ignored"/null/g' coverage/coverage.json
+
       - name: Upload coverage to Codecov
         uses: codecov/codecov-action@v5
         if: matrix.ruby == '3.4'
@@ -62,3 +71,25 @@ jobs:
           token: ${{ secrets.CODECOV_TOKEN }}
           files: coverage/coverage.json
 
+      # The upload step succeeds even when Codecov later fails to process the
+      # report (state "error", 0% coverage), so poll the API and fail loudly.
+      - name: Verify Codecov processed the report
+        if: matrix.ruby == '3.4' && github.event.pull_request.head.repo.fork != true
+        env:
+          SHA: ${{ github.event.pull_request.head.sha || github.sha }}
+        run: |
+          owner="${GITHUB_REPOSITORY%%/*}"
+          repo="${GITHUB_REPOSITORY#*/}"
+          url="https://api.codecov.io/api/v2/github/${owner}/repos/${repo}/commits/${SHA}/"
+          for attempt in $(seq 1 18); do
+            state=$(curl -fsS "$url" | jq -r '.state' || true)
+            echo "Codecov state for ${SHA}: ${state:-unknown} (attempt ${attempt})"
+            case "$state" in
+              complete) exit 0 ;;
+              error)
+                echo "::error::Codecov failed to process the coverage report for ${SHA}"
+                exit 1 ;;
+            esac
+            sleep 10
+          done
+          echo "::warning::Timed out waiting for Codecov to process ${SHA}"

data/CHANGELOG.md

@@ -8,6 +8,13 @@ from v1.0.0 onwards. Prior 0.x releases may include breaking changes between min
 
 ## [Unreleased]
 
+## [1.7.1] - 2026-10-26
+
+### Fixed
+
+- `ractor_safe: true` could hang forever on Ruby 3.x when several threads in the same Ractor called memoized methods (or `reset_all_ractor_memos` and friends) at once. Ruby can lose a wakeup when multiple threads wait in `Ractor.receive_if` on the Ractor's single incoming queue, leaving one caller blocked indefinitely. Each request/reply round trip to the supervisor is now serialized per Ractor; throughput is unchanged since the supervisor already handles requests one at a time.
+- `ractor_safe: true` now works on Ruby 4.0. Ruby 4.0 removed `Ractor.receive_if` and `Ractor#take`, so every call raised `NoMethodError`. On 4.0 each request now gets its own `Ractor::Port` for the supervisor's reply; Ruby 3.x behaviour is unchanged. The `ractor_safe` specs previously skipped themselves on 4.0 and now run there.
+
 ## [1.7.0] - 2026-06-02
 
 ### Added
@@ -268,7 +275,18 @@ from v1.0.0 onwards. Prior 0.x releases may include breaking changes between min
 
 - Initial release
 
-[Unreleased]: https://github.com/eclectic-coding/safe_memoize/compare/v0.7.0...HEAD
+[Unreleased]: https://github.com/eclectic-coding/safe_memoize/compare/v1.7.1...HEAD
+[1.7.1]: https://github.com/eclectic-coding/safe_memoize/compare/v1.7.0...v1.7.1
+[1.7.0]: https://github.com/eclectic-coding/safe_memoize/compare/v1.6.0...v1.7.0
+[1.6.0]: https://github.com/eclectic-coding/safe_memoize/compare/v1.5.0...v1.6.0
+[1.5.0]: https://github.com/eclectic-coding/safe_memoize/compare/v1.4.0...v1.5.0
+[1.4.0]: https://github.com/eclectic-coding/safe_memoize/compare/v1.3.0...v1.4.0
+[1.3.0]: https://github.com/eclectic-coding/safe_memoize/compare/v1.2.0...v1.3.0
+[1.2.0]: https://github.com/eclectic-coding/safe_memoize/compare/v1.1.0...v1.2.0
+[1.1.0]: https://github.com/eclectic-coding/safe_memoize/compare/v1.0.0...v1.1.0
+[1.0.0]: https://github.com/eclectic-coding/safe_memoize/compare/v0.9.0...v1.0.0
+[0.9.0]: https://github.com/eclectic-coding/safe_memoize/compare/v0.8.0...v0.9.0
+[0.8.0]: https://github.com/eclectic-coding/safe_memoize/compare/v0.7.0...v0.8.0
 [0.7.0]: https://github.com/eclectic-coding/safe_memoize/compare/v0.6.3...v0.7.0
 [0.6.3]: https://github.com/eclectic-coding/safe_memoize/compare/v0.6.2...v0.6.3
 [0.6.2]: https://github.com/eclectic-coding/safe_memoize/compare/v0.6.1...v0.6.2

data/README.md

@@ -12,6 +12,57 @@ SafeMemoize is a production-ready, zero-dependency memoization library for Ruby.
 
 Beyond the basics, SafeMemoize ships with TTL expiration (including sliding window refresh via `ttl_refresh:`), LRU cache size capping, conditional caching via `if:`/`unless:` predicates, lifecycle hooks for cache hits, evictions, and expirations, per-instance metrics (hit rate, miss rate, average computation time), targeted and bulk cache invalidation, custom cache key generators, and rich introspection helpers (`memoized?`, `memo_count`, `memo_keys`, `memo_values`, `memo_ttl_remaining`). It preserves method visibility (public, protected, and private) and requires no runtime dependencies.
 
+## Table of Contents
+
+- [The Problem](#the-problem)
+- [How It Works](#how-it-works)
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Basic memoization](#basic-memoization)
+  - [With arguments](#with-arguments)
+  - [Nil and false safety](#nil-and-false-safety)
+  - [Works with private methods](#works-with-private-methods)
+  - [Cache reset](#cache-reset)
+  - [Cache invalidation groups](#cache-invalidation-groups)
+  - [Lifecycle hooks](#lifecycle-hooks)
+  - [TTL expiration](#ttl-expiration)
+  - [Sliding window TTL](#sliding-window-ttl)
+  - [LRU cache size limit](#lru-cache-size-limit)
+  - [Conditional caching](#conditional-caching)
+  - [Cache warm-up and persistence](#cache-warm-up-and-persistence)
+  - [Shared cache](#shared-cache)
+  - [Fiber-local memoization](#fiber-local-memoization)
+  - [Bulk memoization](#bulk-memoization)
+  - [Custom cache keys](#custom-cache-keys)
+  - [Cache inspection](#cache-inspection)
+  - [Cache metrics](#cache-metrics)
+  - [Plugin / extension architecture](#plugin--extension-architecture)
+  - [Automatic cache busting](#automatic-cache-busting)
+  - [Named shared caches](#named-shared-caches)
+  - [Cache namespacing](#cache-namespacing)
+  - [Global configuration](#global-configuration)
+  - [ActiveSupport::Notifications](#activesupportnotifications)
+  - [StatsD](#statsd)
+  - [OpenTelemetry](#opentelemetry)
+  - [Rails request-scope](#rails-request-scope)
+  - [Pluggable cache stores](#pluggable-cache-stores)
+  - [Deprecation](#deprecation)
+- [Circuit breaker for external stores](#circuit-breaker-for-external-stores)
+- [Multi-level caching](#multi-level-caching)
+- [Stampede protection](#stampede-protection)
+- [Per-class default options](#per-class-default-options-safe_memoize_options)
+- [Copy-on-read](#copy-on-read)
+- [Ractor-safe shared cache](#ractor-safe-shared-cache)
+- [Ractor compatibility](#ractor-compatibility)
+- [Development](#development)
+- [Releasing](#releasing)
+- [Public API and versioning guarantee](#public-api-and-versioning-guarantee)
+- [Ruby version support](#ruby-version-support)
+- [Benchmarks](benchmarks/BENCHMARK.md)
+- [Roadmap](#roadmap)
+- [Contributing](#contributing)
+- [License](#license)
+
 ## The Problem
 
 Ruby's common memoization pattern breaks with falsy values: 
@@ -28,62 +79,6 @@ SafeMemoize uses `Hash#key?` to distinguish "not yet cached" from "cached nil/fa
 
 SafeMemoize uses Ruby's `prepend` mechanism. When you call `memoize :method_name`, it creates an anonymous module with a wrapper method and prepends it onto your class. The wrapper calls `super` to invoke the original method and stores the result in a per-instance hash. Thread safety is achieved with a per-instance `Mutex` using double-check locking.
 
-## Features
-
-- [Correctly memoizes `nil` and `false` return values](#nil-and-false-safety)
-- [Caches per unique arguments (positional and keyword)](#with-arguments)
-- [Thread-safe via double-check locking](#how-it-works)
-- [Simple `prepend` + `memoize` API](#usage)
-- [Preserves public, protected, and private method visibility](#works-with-private-methods)
-- [Supports targeted cache invalidation by argument combination](#cache-reset)
-- [Includes a `memoized?` helper for cache inspection](#cache-inspection)
-- [Includes a `memo_count` helper for cache size stats](#cache-inspection)
-- [Includes a `memo_keys` helper for inspecting cached signatures](#cache-inspection)
-- [Includes a `memo_values` helper for inspecting cached signatures and values](#cache-inspection)
-- [Optional TTL expiration support for cached entries](#ttl-expiration)
-- [Sliding window TTL via `ttl_refresh: true`](#sliding-window-ttl)
-- [Optional LRU cache size limit per method via `max_size:`](#lru-cache-size-limit)
-- [Conditional caching via `if:` and `unless:` predicates](#conditional-caching)
-- [Lifecycle hooks for hit, miss, eviction, and expiration events](#lifecycle-hooks)
-- [Per-instance cache metrics (hit rate, miss rate, computation time)](#cache-metrics)
-- [Cache warm-up, export, and restore (`warm_memo`, `dump_memo`, `load_memo`)](#cache-warm-up-and-persistence)
-- [Class-level shared cache via `shared: true` with optional LRU](#shared-cache)
-- [Bulk memoization via `memoize_all` (public, protected, and private)](#bulk-memoization)
-- [Custom cache key generation per method](#custom-cache-keys)
-- [TTL introspection via `memo_ttl_remaining`](#cache-inspection)
-- [Deep single-entry inspection via `memo_inspect`](#cache-inspection)
-- [`ArgumentError` at definition time when memoizing an undefined method](#basic-memoization)
-- [Hook error isolation — hook exceptions never propagate to callers](#lifecycle-hooks)
-- [Deprecation infrastructure for gem authors](#deprecation)
-- [Optional `ActiveSupport::Notifications` integration for Rails observability](#activesupportnotifications)
-- [Optional StatsD adapter for metrics pipelines](#statsd)
-- [Optional OpenTelemetry adapter for distributed tracing](#opentelemetry)
-- [Rails request-scope helpers for controllers and service objects](#rails-request-scope)
-- [Batch cache warm-up via `memo_preload`](#cache-warm-up-and-persistence)
-- [`on_memo_store` hook fires on every cache write](#lifecycle-hooks)
-- [Global default TTL and max size via `SafeMemoize.configure`](#global-configuration)
-- [`memo_touch` resets the expiry clock without recomputing](#ttl-expiration)
-- [`memo_refresh` force-recomputes and re-caches in one call](#cache-inspection)
-- [`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)
-- [Cache namespacing — per-method `namespace:`, class-level `.safe_memoize_namespace=`, and global `Configuration#namespace` for multi-tenant and versioned deployments](#cache-namespacing)
-- [Named shared caches via `shared_cache: "name"` — cross-class cache sharing backed by a globally-registered store](#named-shared-caches)
-- [Automatic cache busting via `cache_bust:` — version-token-based invalidation; works with ActiveRecord `updated_at` and any comparable value](#automatic-cache-busting)
-- [Plugin / extension architecture — `SafeMemoize::Extension` DSL for adding custom `memoize` options and global lifecycle handlers without monkey-patching](#plugin--extension-architecture)
-- [Per-class default options via `safe_memoize_options` — set TTL, max size, copy-on-read, and other defaults for every `memoize` call on the class without repeating them](#per-class-default-options-safe_memoize_options)
-- [Copy-on-read via `copy_on_read: true` — returns a `dup`/`deep_dup` on every cache read to protect shared cached state from caller mutation](#copy-on-read)
-- [Cache invalidation groups via `group:` — tag related methods with a group name and bust them all with a single `reset_memo_group` call](#cache-invalidation-groups)
-- [Circuit breaker for external stores — `Stores::CircuitBreaker` wraps any store adapter and falls back to the per-instance cache when the store is down; configurable error threshold and probe interval](#circuit-breaker-for-external-stores)
-- [Multi-level (L1/L2) caching — `Stores::Multilevel` or `store: [l1, l2]` shorthand; reads from the fastest layer first and promotes on miss](#multi-level-caching)
-- [Stampede protection — `stampede_protection:` option applies the XFetch algorithm to the per-instance cache; `Stores::XFetch` applies it to external stores](#stampede-protection)
-
 ## Installation
 
 Add to your Gemfile:
@@ -122,7 +117,7 @@ end
 
 Calling `memoize` on a method name that does not exist raises `ArgumentError` immediately at class definition time rather than at the first runtime call.
 
-[↑ Back to features](#features)
+[↑ Back to top](#table-of-contents)
 
 ### With arguments
 
@@ -147,7 +142,7 @@ calc.compute(3, 4)  # computes and caches (different args)
 
 Argument arrays, hashes, and strings are deep-frozen into an independent copy when the cache key is built, so mutating arguments after a call cannot corrupt or miss a cached entry.
 
-[↑ Back to features](#features)
+[↑ Back to top](#table-of-contents)
 
 ### Nil and false safety
 
@@ -163,7 +158,7 @@ class Config
 end
 ```
 
-[↑ Back to features](#features)
+[↑ Back to top](#table-of-contents)
 
 ### Works with private methods
 
@@ -184,7 +179,7 @@ class TokenProvider
 end
 ```
 
-[↑ Back to features](#features)
+[↑ Back to top](#table-of-contents)
 
 ### Cache reset
 
@@ -196,7 +191,7 @@ obj.reset_memo(:search, "ruby", page: 2)       # Clears one positional/keyword c
 obj.reset_all_memos                             # Clears all memoized values
 ```
 
-[↑ Back to features](#features)
+[↑ Back to top](#table-of-contents)
 
 ### Cache invalidation groups
 
@@ -269,7 +264,7 @@ end
 
 A method belongs to at most one group at a time; re-memoizing with a different `group:` moves it.
 
-[↑ Back to features](#features)
+[↑ Back to top](#table-of-contents)
 
 ### Lifecycle hooks
 
@@ -347,7 +342,7 @@ end
 
 Set `c.on_hook_error = :raise` to re-raise exceptions instead of swallowing them.
 
-[↑ Back to features](#features)
+[↑ Back to top](#table-of-contents)
 
 ### TTL expiration
 
@@ -379,7 +374,7 @@ obj.memo_refresh(:current_quote)             # Recomputes and re-caches
 obj.memo_refresh(:find, 42)                  # Recomputes for one argument combination
 ```
 
-[↑ Back to features](#features)
+[↑ Back to top](#table-of-contents)
 
 ### Sliding window TTL
 
@@ -398,7 +393,7 @@ end
 
 Without `ttl_refresh:`, the entry expires 300 seconds after it was first cached. With it, the clock resets on every read — the entry is evicted only if the method goes 300 seconds without being called. `ttl_refresh: true` requires `ttl:` to be set and works with both per-instance and `shared: true` memoization.
 
-[↑ Back to features](#features)
+[↑ Back to top](#table-of-contents)
 
 ### LRU cache size limit
 
@@ -433,7 +428,7 @@ memoize :find, max_size: 50, ttl: 300
 
 The `on_evict` hook fires for LRU-evicted entries the same way it does for manual `reset_memo` calls.
 
-[↑ Back to features](#features)
+[↑ Back to top](#table-of-contents)
 
 ### Conditional caching
 
@@ -469,7 +464,7 @@ Both options accept any callable and compose with `ttl:` and `max_size:`:
 memoize :find, if: ->(result) { !result.nil? }, ttl: 60, max_size: 500
 ```
 
-[↑ Back to features](#features)
+[↑ Back to top](#table-of-contents)
 
 ### Cache warm-up and persistence
 
@@ -535,7 +530,7 @@ obj.load_memo(Marshal.load(raw)) if raw
 
 Loaded entries have no TTL — they persist until explicitly reset. Expired entries are excluded from `dump_memo` output, so snapshots never contain stale data.
 
-[↑ Back to features](#features)
+[↑ Back to top](#table-of-contents)
 
 ### Shared cache
 
@@ -585,7 +580,7 @@ memoize :find, shared: true, max_size: 500
 
 Hooks (`on_memo_hit`, `on_memo_miss`, `on_memo_expire`, `on_memo_evict`) fire on the calling instance as usual.
 
-[↑ Back to features](#features)
+[↑ Back to top](#table-of-contents)
 
 ### Fiber-local memoization
 
@@ -627,7 +622,7 @@ obj.reset_all_fiber_memos                # clear all fiber-local entries for thi
 
 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)
+[↑ Back to top](#table-of-contents)
 
 ### Bulk memoization
 
@@ -685,7 +680,7 @@ memoize_all include_protected: true, include_private: true
 
 Inherited methods are never affected regardless of visibility.
 
-[↑ Back to features](#features)
+[↑ Back to top](#table-of-contents)
 
 ### Custom cache keys
 
@@ -734,7 +729,7 @@ svc.clear_custom_keys(:generate)  # Remove generator for one method
 svc.clear_custom_keys             # Remove all custom key generators
 ```
 
-[↑ Back to features](#features)
+[↑ Back to top](#table-of-contents)
 
 ### Cache inspection
 
@@ -780,7 +775,7 @@ obj.memo_inspect(:find, 42)
 
 Returns `nil` when the entry is not cached.
 
-[↑ Back to features](#features)
+[↑ Back to top](#table-of-contents)
 
 ### Cache metrics
 
@@ -810,7 +805,7 @@ obj.cache_metrics_reset(:find)    # Clears metrics for one method only
 
 Metrics are per-instance and reset independently from the cache itself — clearing metrics does not evict cached values.
 
-[↑ Back to features](#features)
+[↑ Back to top](#table-of-contents)
 
 ### Plugin / extension architecture
 
@@ -893,7 +888,7 @@ An extension does not need to `extend SafeMemoize::Extension`. Any object respon
 - Unknown `memoize` keywords raise `ArgumentError` unless a registered extension claims them — typos are still caught.
 - `on_cache_event` handlers run on the main Ractor only; they are silently skipped from worker Ractors.
 
-[↑ Back to features](#features)
+[↑ Back to top](#table-of-contents)
 
 ### Automatic cache busting
 
@@ -954,7 +949,7 @@ obj.reset_memo(:summary)      # clears ALL versions
 - Incompatible with `key:` — both define the cache key shape; raises `ArgumentError` at `memoize` time.
 - Composes with `namespace:`, `ttl:`, `if:`, `unless:`, and `shared_cache:`.
 
-[↑ Back to features](#features)
+[↑ Back to top](#table-of-contents)
 
 ### Named shared caches
 
@@ -1025,7 +1020,7 @@ memoize :find, shared_cache: "orders", namespace: "presenter"  # [:"presenter:fi
 - `register_shared_cache` must be called before the class that uses the name is defined.
 - Test suites should call `SafeMemoize.reset_shared_caches!` in an `after` hook to prevent state leaking between examples.
 
-[↑ Back to features](#features)
+[↑ Back to top](#table-of-contents)
 
 ### Cache namespacing
 
@@ -1086,7 +1081,7 @@ end
 - Namespacing works with all memoize paths (standard, `store:`, `fiber_local:`, `shared:`, `ractor_safe:`).
 - Adding or changing a namespace changes the cache keys, so existing entries become unreachable (they expire naturally or can be cleared by `reset_all_memos`).
 
-[↑ Back to features](#features)
+[↑ Back to top](#table-of-contents)
 
 ### Global configuration
 
@@ -1107,7 +1102,7 @@ SafeMemoize.reset_configuration!
 
 The configure block also accepts `on_hook_error`, `on_deprecation`, `active_support_notifications`, `statsd_client`, `default_store`, and `namespace` (covered in [Hook error isolation](#hook-error-isolation), [Deprecation](#deprecation), [ActiveSupport::Notifications](#activesupportnotifications), [StatsD](#statsd), [Pluggable cache stores](#pluggable-cache-stores), and [Cache namespacing](#cache-namespacing)).
 
-[↑ Back to features](#features)
+[↑ Back to top](#table-of-contents)
 
 ### ActiveSupport::Notifications
 
@@ -1149,7 +1144,7 @@ end
 
 The integration is a no-op when ActiveSupport is not loaded — there is no overhead for non-Rails projects. `active_support_notifications` defaults to `false`.
 
-[↑ Back to features](#features)
+[↑ Back to top](#table-of-contents)
 
 ### StatsD
 
@@ -1175,7 +1170,7 @@ Each call includes two tags: `method:method_name` and `class:ClassName`. The cli
 
 If the client raises, the error is rescued and a warning is emitted to stderr rather than propagated to the caller. `statsd_client` defaults to `nil` (disabled).
 
-[↑ Back to features](#features)
+[↑ Back to top](#table-of-contents)
 
 ### OpenTelemetry
 
@@ -1200,7 +1195,7 @@ SafeMemoize then wraps every cache miss (the actual method call, not cache hits)
 
 Cache hits produce no spans, so tracing overhead is zero for cached calls. The adapter is compatible with any tracer that responds to `in_span(name, attributes:, &block)` — the interface provided by `opentelemetry-sdk`, `opentelemetry-api`, and no-op tracers alike. If `opentelemetry_tracer` is `nil` (the default), the adapter is completely bypassed.
 
-[↑ Back to features](#features)
+[↑ Back to top](#table-of-contents)
 
 ### Rails request-scope
 
@@ -1269,7 +1264,7 @@ end
 
 `SafeMemoize::Rails::Middleware` calls `reset_all_memos` on every tracked instance in the current thread at the end of the request, even if the app raises. Tracking is thread-local, so concurrent requests never interfere. The tracked list is cleared automatically after each reset.
 
-[↑ Back to features](#features)
+[↑ Back to top](#table-of-contents)
 
 ### Pluggable cache stores
 
@@ -1418,7 +1413,7 @@ A per-method `store:` option always takes precedence. Methods using `max_size:`
 
 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)
+[↑ Back to top](#table-of-contents)
 
 ### Deprecation
 
@@ -1449,7 +1444,7 @@ SafeMemoize.configure do |c|
 end
 ```
 
-[↑ Back to features](#features)
+[↑ Back to top](#table-of-contents)
 
 ## Circuit breaker for external stores
 
@@ -1533,7 +1528,7 @@ class ApiService
 end
 ```
 
-[↑ Back to features](#features)
+[↑ Back to top](#table-of-contents)
 
 ## Multi-level caching
 
@@ -1572,7 +1567,7 @@ store   = SafeMemoize::Stores::Multilevel.new(SafeMemoize::Stores::Memory.new, s
 memoize :catalog, store: store, ttl: 300
 ```
 
-[↑ Back to features](#features)
+[↑ Back to top](#table-of-contents)
 
 ## Stampede protection
 
@@ -1629,7 +1624,7 @@ store = SafeMemoize::Stores::XFetch.new(
 )
 ```
 
-[↑ Back to features](#features)
+[↑ Back to top](#table-of-contents)
 
 ## Per-class default options (`safe_memoize_options`)
 
@@ -1668,7 +1663,7 @@ Call with no arguments to clear all class-level defaults:
 MyClass.safe_memoize_options   # clears — subsequent memoize calls use global config or per-call options only
 ```
 
-[↑ Back to features](#features)
+[↑ Back to top](#table-of-contents)
 
 ## Copy-on-read
 
@@ -1706,7 +1701,7 @@ class ReportService
 end
 ```
 
-[↑ Back to features](#features)
+[↑ Back to top](#table-of-contents)
 
 ## Ractor-safe shared cache
 
@@ -1727,7 +1722,7 @@ end
 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
+result = Ractor.new(PriceService) { |s| s.new.fetch_price(42) }.value  # .take on Ruby 3.x
 ```
 
 ### How it works
@@ -1735,7 +1730,7 @@ result = Ractor.new(PriceService) { |s| s.new.fetch_price(42) }.take
 - 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.
+- **Thread safety** inside the main Ractor (multiple threads): on Ruby 4.0+ each call replies through its own `Ractor::Port`, so callers never share a queue. On Ruby 3.x, replies are matched by per-call tags (`Thread.current.object_id`) with `Ractor.receive_if`, and each send/receive pair is serialized per Ractor because concurrent `receive_if` waiters can otherwise lose a wakeup and hang.
 - `ttl:` is supported. Expired entries are skipped by the supervisor's `:fetch` handler.
 
 ### Constraints
@@ -1761,7 +1756,7 @@ PriceService.reset_ractor_memo(:fetch_price)         # → clear all entries for
 PriceService.reset_all_ractor_memos                  # → clear entire shared cache
 ```
 
-[↑ Back to features](#features)
+[↑ Back to top](#table-of-contents)
 
 ## Ractor compatibility
 
@@ -1779,7 +1774,7 @@ Regular `memoize` (without `ractor_safe: true`) is **not Ractor-compatible**. Pa
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `bundle exec rspec` to run the tests. You can also run `bin/console` for an interactive prompt.
 
-To run the benchmark suite: `bundle exec ruby benchmarks/benchmark.rb`.
+To run the benchmark suite: `bundle exec ruby benchmarks/benchmark.rb`. Pre-recorded results and analysis are in [benchmarks/BENCHMARK.md](benchmarks/BENCHMARK.md).
 
 To generate API documentation locally: `bundle exec rake doc`. Output is written to `doc/` (gitignored). The online reference is published automatically to [RubyDoc.info](https://rubydoc.info/gems/safe_memoize) on every release. Install `memery` and `memo_wise` first if you want comparison columns against those gems.
 

data/benchmarks/BENCHMARK.md

@@ -0,0 +1,114 @@
+# SafeMemoize Benchmark Results
+
+Run with `bundle exec ruby benchmarks/benchmark.rb`.
+
+**Environment:** Ruby 3.4.8 (arm64-darwin25, PRISM) · `benchmark-ips` 5 s measurement / 2 s warmup
+
+---
+
+## What is being measured
+
+SafeMemoize is compared against two vanilla Ruby baselines:
+
+| Label | Pattern | Correctness |
+|---|---|---|
+| `raw \|\|= (unsafe)` | `@v \|\|= compute` | Broken — re-runs if result is `nil` or `false` |
+| `raw safe ivar` | `return @v if defined?(@v); @v = compute` | Correct |
+| `safe_memoize` | `prepend SafeMemoize` + `memoize :method` | Correct |
+
+The raw patterns are intentionally simple and carry none of SafeMemoize's feature overhead (thread safety, argument keying, TTL, hooks, metrics). The numbers below quantify exactly what that feature set costs.
+
+---
+
+## Results
+
+### 1. Zero-arg cache HIT — steady-state throughput
+
+A primed object called repeatedly. This is the hot path.
+
+| Implementation | i/s | ns/call | vs fastest |
+|---|---|---|---|
+| `raw safe ivar` | 21.51 M | 46.5 | — |
+| `raw \|\|= (unsafe)` | 16.69 M | 59.9 | 1.29× slower |
+| `safe_memoize` | 296.8 K | 3,370 | **72×** slower |
+
+**Takeaway:** SafeMemoize's hit path costs ~3.4 µs per call — the price of a hash lookup, mutex check, and key construction. For methods that are called millions of times per second in a tight loop, raw ivars win. For methods that do real work (DB queries, HTTP, serialization), this overhead is negligible.
+
+---
+
+### 2. Zero-arg cache MISS — first-call overhead
+
+A fresh instance is created each iteration so every call is a miss.
+
+| Implementation | i/s | µs/call | vs fastest |
+|---|---|---|---|
+| `raw safe ivar` | 8.47 M | 0.12 | — |
+| `safe_memoize` | 189.6 K | 5.28 | **45×** slower |
+
+**Takeaway:** The miss path allocates the cache hash, builds the key, and acquires the mutex — ~5 µs. Still fast in absolute terms; any method body doing more than a trivial computation will dominate.
+
+---
+
+### 3. With-argument cache HIT — keyed lookup
+
+A primed object called with the same argument each iteration.
+
+| Implementation | i/s | ns/call | vs fastest |
+|---|---|---|---|
+| `raw safe ivar` | 14.17 M | 70.6 | — |
+| `safe_memoize` | 289.2 K | 3,460 | **49×** slower |
+
+**Takeaway:** The argument hash lookup adds roughly the same overhead as the zero-arg case. Key construction (deep-freeze copy of args) dominates, not the hash lookup itself.
+
+---
+
+### 4. Fast path vs locked path (internal)
+
+Both are `safe_memoize`. Adding `max_size:` enables LRU tracking, which holds the mutex for the full read/write cycle.
+
+| Configuration | i/s | µs/call | vs fast path |
+|---|---|---|---|
+| No `max_size:` (fast path) | 287.7 K | 3.48 | — |
+| `max_size: 100` (locked path) | 218.0 K | 4.59 | 1.32× slower |
+
+**Takeaway:** LRU costs an extra ~1.1 µs per hit. Use it when eviction matters; skip it for unbounded caches.
+
+---
+
+### 5. Shared cache vs instance cache (internal)
+
+Both are `safe_memoize`. `shared: true` stores results on the class rather than the instance.
+
+| Configuration | i/s | µs/call | difference |
+|---|---|---|---|
+| Instance cache | 292.5 K | 3.42 | — |
+| Shared cache | 275.3 K | 3.63 | within margin of error |
+
+**Takeaway:** Class-level shared storage is essentially free compared to per-instance caching. The mutex contention at the class level does not measurably affect single-threaded throughput.
+
+---
+
+### 6. Concurrent throughput — 8 threads × 50,000 iterations
+
+| Implementation | Total time | i/s |
+|---|---|---|
+| `raw safe ivar` | 0.033 s | 12.01 M |
+| `safe_memoize` (instance cache) | 1.363 s | 293.4 K |
+| `safe_memoize` (shared cache) | 1.393 s | 287.1 K |
+
+**Takeaway:** Under real thread contention the raw ivar baseline has no locking at all — it is technically unsafe here. SafeMemoize's per-instance mutex serialises writes correctly at ~293 K i/s; the class-level shared mutex performs identically at ~287 K i/s.
+
+---
+
+## Summary
+
+| Scenario | SafeMemoize overhead |
+|---|---|
+| Hot cache hit (zero-arg) | ~3.4 µs — 72× vs raw ivar |
+| Hot cache hit (with args) | ~3.5 µs — 49× vs raw ivar |
+| First call / cache miss | ~5.3 µs — 45× vs raw ivar |
+| LRU enabled (`max_size:`) | +1.1 µs vs fast path |
+| Shared vs instance cache | no measurable difference |
+| Concurrent throughput | ~293 K i/s (thread-safe) |
+
+SafeMemoize is slower than a raw instance variable in absolute terms, but the overhead is measured in **microseconds**, not milliseconds. Any method that does I/O, calls a database, hits an external API, or performs non-trivial computation will completely dominate the memoization overhead — and that is precisely the use case SafeMemoize is designed for.

data/benchmarks/README.md

@@ -65,4 +65,6 @@ bundle exec ruby benchmarks/benchmark.rb
    safe_memoize (shared) ~323 K i/s
 ```
 
-Results vary by hardware, Ruby version, and GVL scheduling. Run on your own hardware for authoritative numbers.
+Results vary by hardware, Ruby version, and GVL scheduling. Run on your own hardware for authoritative numbers.
+
+For a full recorded run with analysis, see [BENCHMARK.md](BENCHMARK.md).

data/lib/safe_memoize/class_methods.rb

@@ -958,9 +958,7 @@ module SafeMemoize
 
             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]
+            response = RactorSharedMethods.round_trip(supervisor, :fetch, cache_key)
 
             if response[:hit]
               record_cache_hit(cache_key)
@@ -985,8 +983,7 @@ module SafeMemoize
               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 = RactorSharedMethods.round_trip(supervisor, :store, cache_key, record)
             stored_record = stored[:stored]
 
             record_cache_miss(cache_key, elapsed_time)

data/lib/safe_memoize/ractor_shared_methods.rb

@@ -15,9 +15,65 @@ module SafeMemoize
   # - +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.
+  #   threads, responses are matched by thread identity and each send/receive pair
+  #   is serialized per Ractor, so concurrent callers do not consume each other's
+  #   replies or lose a wakeup.
   module RactorSharedMethods
+    MUTEX_KEY = :__safe_memo_ractor_mutex__
+
+    # Ruby 4.0 replaced +Ractor.receive_if+ with +Ractor::Port+.
+    PORTS = defined?(Ractor::Port) ? true : false
+
+    # Sends a request to +supervisor+ and blocks until its reply arrives,
+    # returning the reply payload.
+    def self.round_trip(supervisor, op, *args)
+      # :nocov:
+      return round_trip_via_port(supervisor, op, *args) if PORTS
+      # :nocov:
+
+      round_trip_via_queue(supervisor, op, *args)
+    end
+
+    # Ruby 4.0+: each call gets its own port, so callers never share a queue.
+    # :nocov:
+    def self.round_trip_via_port(supervisor, op, *args)
+      port = Ractor::Port.new
+      supervisor.send(Ractor.make_shareable([port, Thread.current.object_id, op, *args]))
+      port.receive[1]
+    ensure
+      port&.close
+    end
+    # :nocov:
+
+    # Ruby 3.x: replies are matched by thread identity, but every thread in a
+    # Ractor waits on that Ractor's single incoming queue. Ruby 3.x can lose a
+    # wakeup when several threads sit in +Ractor.receive_if+ at once, leaving one
+    # waiting forever, so the send/receive pair is serialized per Ractor. The
+    # supervisor handles requests one at a time anyway, so this costs no
+    # throughput.
+    def self.round_trip_via_queue(supervisor, op, *args)
+      tag = Thread.current.object_id
+      msg = Ractor.make_shareable([Ractor.current, tag, op, *args])
+
+      ractor_mutex.synchronize do
+        supervisor.send(msg)
+        Ractor.receive_if { |m| m.is_a?(Array) && m[0] == tag }[1]
+      end
+    end
+
+    # Per-Ractor mutex held in Ractor-local storage (a plain +Mutex+ constant is
+    # not Ractor-shareable).
+    def self.ractor_mutex
+      Ractor.current[MUTEX_KEY] ||
+        if Ractor.respond_to?(:store_if_absent)
+          Ractor.store_if_absent(MUTEX_KEY) { Mutex.new }
+        else
+          # :nocov:
+          Ractor.current[MUTEX_KEY] ||= Mutex.new # Ruby 3.3 lacks store_if_absent
+          # :nocov:
+        end
+    end
+
     # Clears one or all entries from the Ractor-safe shared cache.
     #
     # @param method_name [Symbol, String]
@@ -76,13 +132,8 @@ module SafeMemoize
     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]
+      RactorSharedMethods.round_trip(supervisor, op, *args)
     end
 
     # Creates the supervisor Ractor that owns this class's Ractor-safe shared cache.

data/lib/safe_memoize/release_tooling.rb

@@ -10,6 +10,7 @@ module SafeMemoize
     VERSION_PATTERN = /VERSION = "[^"]+"/
     SEMVER_PATTERN = /\A\d+\.\d+\.\d+(?:[-.][0-9A-Za-z]+(?:[.-][0-9A-Za-z]+)*)?\z/
     UNRELEASED_HEADING = "## [Unreleased]"
+    UNRELEASED_LINK = %r{^\[Unreleased\]: (?<base>\S+)/compare/v(?<previous>[^.\s]\S*?)\.\.\.HEAD$}
 
     def normalize_version(version)
       normalized_version = version.to_s.sub(/\Av/, "")
@@ -43,7 +44,24 @@ module SafeMemoize
         raise ArgumentError, "CHANGELOG.md already contains #{normalized_version}"
       end
 
-      contents.sub(UNRELEASED_HEADING, "#{UNRELEASED_HEADING}\n\n#{release_heading}")
+      contents = contents.sub(UNRELEASED_HEADING, "#{UNRELEASED_HEADING}\n\n#{release_heading}")
+      update_version_links(contents, normalized_version)
+    end
+
+    # Keeps the reference-style link definitions at the bottom of the CHANGELOG
+    # in sync: points [Unreleased] at the new tag and adds a compare link for
+    # the new version. Left untouched when no [Unreleased] link is present.
+    def update_version_links(contents, version)
+      match = contents.match(UNRELEASED_LINK)
+      return contents unless match
+
+      base = match[:base]
+      replacement = [
+        "[Unreleased]: #{base}/compare/v#{version}...HEAD",
+        "[#{version}]: #{base}/compare/v#{match[:previous]}...v#{version}"
+      ].join("\n")
+
+      contents.sub(UNRELEASED_LINK) { replacement }
     end
 
     # Removes milestone sections from ROADMAP.md where every feature row has

data/lib/safe_memoize/version.rb

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

data/sig/safe_memoize.rbs

@@ -251,6 +251,14 @@ module SafeMemoize
   end
 
   module RactorSharedMethods
+    MUTEX_KEY: Symbol
+    PORTS: bool
+
+    def self.round_trip: (untyped supervisor, Symbol op, *untyped args) -> untyped
+    def self.round_trip_via_port: (untyped supervisor, Symbol op, *untyped args) -> untyped
+    def self.round_trip_via_queue: (untyped supervisor, Symbol op, *untyped args) -> untyped
+    def self.ractor_mutex: () -> Thread::Mutex
+
     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

metadata

@@ -1,28 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: safe_memoize
 version: !ruby/object:Gem::Version
-  version: 1.7.0
+  version: 1.7.1
 platform: ruby
 authors:
 - Chuck Smith
 bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
-dependencies:
-- !ruby/object:Gem::Dependency
-  name: simplecov
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.22'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.22'
+dependencies: []
 description: 'SafeMemoize is a production-ready, zero-dependency memoization library
   for Ruby. It uses Ruby''s prepend mechanism to wrap methods with a thread-safe cache
   (Mutex + double-check locking) that correctly handles nil and false return values
@@ -49,6 +35,7 @@ files:
 - ROADMAP.md
 - Rakefile
 - UPGRADING.md
+- benchmarks/BENCHMARK.md
 - benchmarks/README.md
 - benchmarks/benchmark.rb
 - codecov.yml