sidekiq-ratomic-pool 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3c1be6120972266a46da7e3b1646f695b015be76d366c231374d47d93aae1ac6
-  data.tar.gz: 85b6f68ea11bcc778afd3874551577b364bda3af6b5e8e9084c9e249ee18f85b
+  metadata.gz: f6497422ce457ce3e5aab57c5e1d7de44aec7b7a6f2784e83a58c0a8419f8b19
+  data.tar.gz: 36f559671bcf385abe58c0d98d9762eb952d97b70faa8ec4830a730106aa03b1
 SHA512:
-  metadata.gz: 065052f3df563140c3928c37d4c4953ab4c1297760aa046ec6c91cd41e90b6debefa4aea28b13399975c4556b50a59e986127cd70bf4f060652a6579cdc13f5b
-  data.tar.gz: a045612004cdd32f615e4dfbb4eacab6240257d06ae68ecaa02d322a479933d24c1f1a202339effc8d61c07f9b9502ccf175adcc337d6e19918e3b1382a52605
+  metadata.gz: 79fef0ed157daa34e338156639ae19346118ab2f72b284d242da0f592ee6910ec19f33433ed6cec0044e1303df633ae47f1af21d2d5c13d943b7015a10ae8e42
+  data.tar.gz: e3ea3f1ed5016670de28fcca67629a599e8ef491915114aa3bff5509920d9e97e3b257380c3bba6e18d178c621d2f916d502b04836743bb533b35c77a527aca3

data/CHANGELOG.md

@@ -1,5 +1,44 @@
 ## [Unreleased]
 
+## [0.3.0] - 2026-08-26
+
+- Added a dedicated `smoke_test/benchmark/` harness for comparative end-to-end
+  throughput measurements using real Redis, Sidekiq, and Ratomic pooling.
+- Added configurable benchmark workloads with elapsed-time, jobs-per-second, and
+  Sidekiq process/thread scheduling output.
+- Added a matched `connection_pool` comparison runner using the same Redis,
+  Sidekiq, pooling, health-check, and workload settings.
+- Added a Ractor-native `4 × 20` benchmark and a four-process Sidekiq benchmark
+  demonstrating 80 total worker/resource capacity across independent runtimes.
+- Made the Ractor benchmark scalable for large job counts by using fixed worker
+  threads with queued jobs instead of creating one Ruby thread per job.
+- Added explicit Ractor-shareability validation for resource factories with a
+  clear configuration error for unsupported factory state.
+- Added custom validator callability validation and regression coverage for the
+  new Ractor-boundary configuration checks.
+- Added configurable LocalPool checkout timeouts through `pool_timeout`, with
+  synchronized middleware runtime adoption and RBS coverage.
+- Expanded the host-owned Ractor adapter with CPU-based defaults, bounded job
+  queues, configurable topology/workload controls, per-Ractor activity metrics,
+  and controlled failure cancellation/reporting.
+- Aligned native and four-process Sidekiq benchmark defaults for workload and
+  checkout timeout, added runtime/version/topology metadata, and hardened short
+  benchmark snapshot handling.
+- Linked the benchmark from the smoke-test documentation.
+- Expanded YARD documentation for all public `Sidekiq::Ratomic::Pool` attribute
+  readers and clarified the host-owned Ractor integration contract.
+- Added elapsed-time and jobs-per-second metrics to the host-owned Ractor
+  adapter for direct comparison with the Sidekiq benchmark.
+- Added Redis server version metadata to the real-Redis benchmark runners.
+- Converted the host-owned Ractor adapter to real Redis resources and persisted
+  a reproducible command for comparing its topology and throughput.
+- Aligned the `connection_pool` comparison runner with the Ratomic benchmark's
+  knobs, Redis workload, metadata, and output shape for apples-to-apples runs.
+- Enforced a single in-flight half-open circuit probe with concurrent fast
+  failure for competing callers.
+- Added regression coverage for host-coordinated Ractor cancellation and
+  simultaneous failure isolation across multiple Ractors.
+
 ## [0.2.0] - 2026-08-25
 
 - Added a real Redis-backed `smoke_test/` harness with standalone Sidekiq client

data/README.md

@@ -27,11 +27,14 @@ and worker pool accessor pattern.
 
 ## Features
 
-- **Ractor-Local Isolation**: Each Ractor lazily owns its resources through `Ratomic::LocalPool`; threads within the same Ractor share that Ractor-local pool.
+- **Ractor-Local Isolation**: A pool runtime used inside a Ractor lazily owns
+  its resources through `Ratomic::LocalPool`; threads within that Ractor share
+  its Ractor-local pool.
 - **Circuit Breaker Pattern**: Trips open after a configurable threshold of checkout, health-check, or configured retryable I/O failures.
 - **Exponential Backoff**: Applies increasing retry delays to transient checkout and retryable resource-operation failures.
 - **Automated Health Probes**: Validates resources with `ping`, `active?`, or a caller-supplied validator before use.
 - **Configurable Failure Policy**: Non-retryable worker exceptions propagate without changing circuit state, avoiding accidental duplicate work.
+- **Ratomic-Native Failure Accounting**: Tracks circuit-breaker failures with the Ractor-shareable `Ratomic::Counter` primitive instead of adding `concurrent-ruby`.
 
 ## Usage
 
@@ -50,6 +53,7 @@ Sidekiq.configure_server do |config|
     chain.add Sidekiq::Ratomic::Pool,
       pool_name: :redis_pool,
       size: 10,
+      pool_timeout: 1,
       max_retries: 3,
       retry_delay: 0.2,
       cb_threshold: 5,
@@ -69,6 +73,81 @@ Resource checkout/health failures and configured retryable I/O errors use expone
 Other exceptions raised by the worker block propagate without being retried, preventing
 accidental duplication of non-idempotent work.
 
+### Host-owned Ractor scheduling
+
+This gem provides Ractor-safe, Ractor-local resource ownership; it does not
+create Ractors or dispatch Sidekiq jobs into them. The host framework or
+application owns Ractor creation, job routing, supervision, and shutdown.
+
+`Sidekiq::Ratomic::Pool` contains mutable circuit-breaker coordination state and
+is not itself required to be Ractor-shareable. A Ractor-aware host should pass
+only shareable configuration and factory data into each Ractor, construct that
+Ractor's pool runtime there, and execute the resource-backed work inside the
+same Ractor:
+
+```ruby
+PoolInput = Data.define(:pool_name, :size, :pool_timeout, :factory, :jobs)
+
+ractor = Ractor.new(
+  Ractor.make_shareable(
+    PoolInput.new(:redis_pool, 20, 1, RedisFactory.new(ENV.fetch('REDIS_URL')), 100)
+  )
+) do |input|
+  pool = Sidekiq::Ratomic::Pool.new(
+    pool_name: input.pool_name,
+    size: input.size,
+    pool_timeout: input.pool_timeout,
+    factory: input.factory
+  )
+
+  input.jobs.times do
+    pool.with { |resource| resource.call('PING') }
+  end
+
+  pool.close
+  :complete
+end
+
+ractor.value
+```
+
+Threads created by the host inside that Ractor use the same Ractor-local pool.
+Resources must not be returned to, or used by, another Ractor. See the
+[`Ractor-local pooling implementation plan`](docs/ractor-local-pooling-implementation-plan.md)
+for the integration contract and rollout criteria.
+
+The opt-in host adapter example demonstrates bounded dispatch, real Redis
+connections, and per-Ractor activity metrics without making Ractor scheduling
+part of the gem:
+
+```bash
+cd smoke_test
+docker compose up -d redis
+REDIS_URL="${REDIS_URL:-redis://127.0.0.1:6380/0}" \
+RACTOR_NATIVE_COUNT=4 \
+RACTOR_NATIVE_THREADS=20 \
+RATOMIC_POOL_SIZE=20 \
+RATOMIC_POOL_TIMEOUT=1 \
+RACTOR_QUEUE_CAPACITY=40 \
+BENCHMARK_JOBS_PER_RACTOR=5000 \
+BENCHMARK_WORK_SECONDS=0.05 \
+bundle exec ruby ./benchmark/ractor_host_adapter.rb
+```
+
+The adapter defaults its Ractor count to `Etc.nprocessors` when the variable
+is omitted. That CPU-based default belongs to the example only; production
+applications remain responsible for choosing and supervising their topology.
+The adapter performs real Redis `PING`, `INCR`, and `HSET` operations and
+reports Ruby, Sidekiq, Ratomic, and Redis versions, elapsed time, throughput,
+and per-Ractor results. With four Ractors, the command above processes 20,000
+jobs and demonstrates four independent pools of 20 resources, shared by 20
+threads inside each Ractor.
+
+The circuit breaker uses `Ratomic::Counter` for its failure count. This keeps the
+counter aligned with Ratomic's Ractor-safe primitive model and avoids a separate
+`concurrent-ruby` production dependency; the pool mutex still protects the
+failure-count and circuit-state transition as one operation.
+
 ## Smoke test
 
 The [`smoke_test/`](smoke_test/) harness runs Redis in Docker, starts a standalone
@@ -80,3 +159,6 @@ Sidekiq worker threads and the CPU core (`PSR`) on which they were recently sche
 cd smoke_test
 ./run.sh
 ```
+
+For comparative throughput measurements, see the [`smoke_test/benchmark/`](smoke_test/benchmark/)
+harness.

data/lib/sidekiq/ratomic/pool/version.rb

@@ -6,7 +6,7 @@ module Sidekiq
   module Ratomic
     class Pool
       # Current gem version.
-      VERSION = '0.2.0'
+      VERSION = '0.3.0'
     end
   end
 end

data/lib/sidekiq/ratomic/pool.rb

@@ -15,16 +15,50 @@ module Sidekiq
     # with exponential backoff. Persistent failures open the circuit breaker.
     # rubocop:disable Metrics/ClassLength
     class Pool
-      attr_reader :pool_name, :size, :max_retries, :retry_delay, :validator, :cb_threshold, :cb_timeout,
-                  :retryable_errors
+      # Name of the worker accessor populated by the middleware.
+      # @return [Symbol]
+      attr_reader :pool_name
+
+      # Maximum number of resources owned by each Ractor-local pool.
+      # @return [Integer]
+      attr_reader :size
+
+      # Maximum time to wait for a resource checkout.
+      # @return [Numeric, nil] seconds, or nil to wait indefinitely
+      attr_reader :pool_timeout
+
+      # Maximum number of retries for checkout and configured retryable failures.
+      # @return [Integer]
+      attr_reader :max_retries
+
+      # Base delay used for exponential retry backoff.
+      # @return [Numeric] seconds
+      attr_reader :retry_delay
+
+      # Callback used to validate a checked-out resource.
+      # @return [#call]
+      attr_reader :validator
+
+      # Number of recorded failures required to open the circuit.
+      # @return [Integer]
+      attr_reader :cb_threshold
+
+      # Time an open circuit remains open before a half-open probe.
+      # @return [Numeric] seconds
+      attr_reader :cb_timeout
+
+      # Exception classes treated as retryable worker/resource failures.
+      # @return [Array<Class>]
+      attr_reader :retryable_errors
 
       # rubocop:disable Metrics/MethodLength
-      def initialize(options = nil, pool_name: nil, size: 10, max_retries: 3, retry_delay: 0.2,
+      def initialize(options = nil, pool_name: nil, size: 10, pool_timeout: 1.0, max_retries: 3, retry_delay: 0.2,
                      cb_threshold: 5, cb_timeout: 30, validator: nil,
                      retryable_errors: [IOError, SystemCallError, Timeout::Error], factory: nil, &block)
         normalize_options!(options) do |config|
           pool_name = config.fetch(:pool_name, pool_name)
           size = config.fetch(:size, size)
+          pool_timeout = config.fetch(:pool_timeout, pool_timeout)
           max_retries = config.fetch(:max_retries, max_retries)
           retry_delay = config.fetch(:retry_delay, retry_delay)
           cb_threshold = config.fetch(:cb_threshold, cb_threshold)
@@ -38,10 +72,13 @@ module Sidekiq
         raise ArgumentError, 'A pool_name must be provided' unless pool_name
         raise ArgumentError, 'A resource factory must be provided' unless factory
 
-        validate_options!(size, max_retries, retry_delay, cb_threshold, cb_timeout)
+        validate_options!(
+          size:, pool_timeout:, max_retries:, retry_delay:, cb_threshold:, cb_timeout:
+        )
 
         @pool_name = pool_name.to_sym
         @size = size
+        @pool_timeout = pool_timeout
         @max_retries = max_retries
         @retry_delay = retry_delay
         @cb_threshold = cb_threshold
@@ -50,10 +87,12 @@ module Sidekiq
         @retryable_errors = retryable_errors.freeze
         @state_mutex = Mutex.new
         @failure_count = ::Ratomic::Counter.new
-        @state_holder = { state: :closed, last_state_change: monotonic_time }
+        @state_holder = { state: :closed, last_state_change: monotonic_time, probe_in_flight: false }
+
+        raise ArgumentError, 'validator must respond to call' unless validator.nil? || validator.respond_to?(:call)
 
-        shareable_factory = Ractor.make_shareable(factory)
-        @local_pool = ::Ratomic::LocalPool.new(size: @size, factory: shareable_factory)
+        shareable_factory = make_shareable_factory(factory)
+        @local_pool = ::Ratomic::LocalPool.new(size: @size, timeout: @pool_timeout, factory: shareable_factory)
       end
 
       # Share one pool runtime across Sidekiq's per-job middleware instances.
@@ -97,7 +136,7 @@ module Sidekiq
 
       # Check out a healthy resource and yield it to the caller.
       def with
-        check_circuit_state!
+        probe_reserved = check_circuit_state!
         attempts = 0
         work_failed = false
 
@@ -116,7 +155,10 @@ module Sidekiq
             result
           end
         rescue StandardError => e
-          raise unless !work_failed || retryable_error?(e)
+          unless !work_failed || retryable_error?(e)
+            release_half_open_probe if probe_reserved
+            raise
+          end
 
           record_failure
           if attempts <= @max_retries && state != :open
@@ -132,10 +174,7 @@ module Sidekiq
       # Return the current circuit-breaker state.
       def state
         @state_mutex.synchronize do
-          if @state_holder[:state] == :open && monotonic_time - @state_holder[:last_state_change] > @cb_timeout
-            @state_holder[:state] = :half_open
-            @state_holder[:last_state_change] = monotonic_time
-          end
+          transition_to_half_open_if_ready
           @state_holder[:state]
         end
       end
@@ -143,9 +182,20 @@ module Sidekiq
       private
 
       def check_circuit_state!
-        return unless state == :open
-
-        raise Pool::CircuitOpenError, 'Circuit breaker is open'
+        @state_mutex.synchronize do
+          transition_to_half_open_if_ready
+          case @state_holder[:state]
+          when :open
+            raise Pool::CircuitOpenError, 'Circuit breaker is open'
+          when :half_open
+            raise Pool::CircuitOpenError, 'Circuit breaker probe is in flight' if @state_holder[:probe_in_flight]
+
+            @state_holder[:probe_in_flight] = true
+            true
+          else
+            false
+          end
+        end
       end
 
       def verify_health(resource)
@@ -162,9 +212,11 @@ module Sidekiq
         error.is_a?(StandardError) && !error.is_a?(Pool::CheckoutError)
       end
 
-      def validate_options!(size, max_retries, retry_delay, cb_threshold, cb_timeout)
+      def validate_options!(size:, pool_timeout:, max_retries:, retry_delay:, cb_threshold:, cb_timeout:)
         validations = [
           [size.is_a?(Integer) && size.positive?, 'size must be a positive Integer'],
+          [pool_timeout.nil? || (pool_timeout.is_a?(Numeric) && pool_timeout >= 0),
+           'pool_timeout must be numeric or nil and non-negative'],
           [max_retries.is_a?(Integer) && max_retries >= 0, 'max_retries must be a non-negative Integer'],
           [retry_delay.is_a?(Numeric) && retry_delay >= 0, 'retry_delay must be non-negative'],
           [cb_threshold.is_a?(Integer) && cb_threshold.positive?, 'cb_threshold must be a positive Integer'],
@@ -180,7 +232,8 @@ module Sidekiq
         raise ArgumentError, 'middleware options must be a Hash' unless options.is_a?(Hash)
 
         config = options.transform_keys(&:to_sym)
-        allowed = %i[pool_name size max_retries retry_delay cb_threshold cb_timeout validator retryable_errors factory]
+        allowed = %i[pool_name size pool_timeout max_retries retry_delay cb_threshold cb_timeout validator
+                     retryable_errors factory]
         unknown = config.keys - allowed
         raise ArgumentError, "unknown middleware options: #{unknown.join(', ')}" unless unknown.empty?
 
@@ -189,6 +242,7 @@ module Sidekiq
 
       def adopt_runtime(runtime)
         @local_pool = runtime.instance_variable_get(:@local_pool)
+        @pool_timeout = runtime.instance_variable_get(:@pool_timeout)
         @state_mutex = runtime.instance_variable_get(:@state_mutex)
         @failure_count = runtime.instance_variable_get(:@failure_count)
         @state_holder = runtime.instance_variable_get(:@state_holder)
@@ -205,7 +259,10 @@ module Sidekiq
         @state_mutex.synchronize do
           failure_count = @failure_count.value
           @failure_count.decrement(failure_count) unless failure_count.zero?
-          @state_holder[:state] = :closed if @state_holder[:state] == :half_open
+          if @state_holder[:state] == :half_open
+            @state_holder[:state] = :closed
+            @state_holder[:probe_in_flight] = false
+          end
         end
       end
 
@@ -215,13 +272,35 @@ module Sidekiq
           if @failure_count.value >= @cb_threshold || @state_holder[:state] == :half_open
             @state_holder[:state] = :open
             @state_holder[:last_state_change] = monotonic_time
+            @state_holder[:probe_in_flight] = false
           end
         end
       end
 
+      def release_half_open_probe
+        @state_mutex.synchronize do
+          @state_holder[:probe_in_flight] = false
+        end
+      end
+
+      def transition_to_half_open_if_ready
+        return unless @state_holder[:state] == :open
+        return unless monotonic_time - @state_holder[:last_state_change] > @cb_timeout
+
+        @state_holder[:state] = :half_open
+        @state_holder[:last_state_change] = monotonic_time
+        @state_holder[:probe_in_flight] = false
+      end
+
       def monotonic_time
         Process.clock_gettime(Process::CLOCK_MONOTONIC)
       end
+
+      def make_shareable_factory(factory)
+        Ractor.make_shareable(factory)
+      rescue Ractor::Error, TypeError => e
+        raise ArgumentError, "resource factory must be Ractor-shareable: #{e.message}"
+      end
     end
     # rubocop:enable Metrics/MethodLength
     # rubocop:enable Metrics/ClassLength

data/sig/sidekiq/ratomic/pool.rbs

@@ -14,6 +14,7 @@ module Sidekiq
 
       attr_reader pool_name: Symbol
       attr_reader size: Integer
+      attr_reader pool_timeout: Numeric?
       attr_reader max_retries: Integer
       attr_reader retry_delay: untyped
       attr_reader validator: ^(untyped) -> bool
@@ -25,6 +26,7 @@ module Sidekiq
         ?untyped options,
         ?pool_name: (Symbol | String),
         ?size: Integer,
+        ?pool_timeout: Numeric?,
         ?max_retries: Integer,
         ?retry_delay: Numeric,
         ?cb_threshold: Integer,
@@ -41,7 +43,14 @@ module Sidekiq
       def with: () { (untyped) -> untyped } -> untyped
       def state: () -> Symbol
       private
-      def validate_options!: (untyped, untyped, untyped, untyped, untyped) -> void
+      def validate_options!: (
+        size: untyped,
+        pool_timeout: untyped,
+        max_retries: untyped,
+        retry_delay: untyped,
+        cb_threshold: untyped,
+        cb_timeout: untyped
+      ) -> void
       def normalize_options!: (untyped) { (Hash[Symbol, untyped]) -> void } -> void
       def adopt_runtime: (instance) -> void
       def check_circuit_state!: () -> void
@@ -51,7 +60,10 @@ module Sidekiq
       def default_validator: (untyped) -> bool
       def record_success: () -> void
       def record_failure: () -> void
+      def release_half_open_probe: () -> void
+      def transition_to_half_open_if_ready: () -> void
       def monotonic_time: () -> Float
+      def make_shareable_factory: (untyped) -> untyped
     end
   end
 end

data/smoke_test/benchmark/client.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'sidekiq'
+require 'redis-client'
+require_relative 'worker'
+
+redis_url = ENV.fetch('REDIS_URL', 'redis://127.0.0.1:6379/0').freeze
+job_count = Integer(ENV.fetch('BENCHMARK_JOB_COUNT', '100'))
+timeout = Integer(ENV.fetch('BENCHMARK_TIMEOUT', '120'))
+run_id = ENV.fetch('BENCHMARK_RUN_ID', Process.clock_gettime(Process::CLOCK_REALTIME, :nanosecond).to_s)
+redis = RedisClient.config(url: redis_url).new_client
+Sidekiq.configure_client { |config| config.redis = { url: redis_url } }
+
+redis.call('DEL', SmokeBenchmark::COUNT_KEY, SmokeBenchmark::RESULTS_KEY)
+started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+job_ids = job_count.times.map do |index|
+  job_id = "#{run_id}-#{index}"
+  Sidekiq::Client.push('class' => SmokeBenchmark::RedisBenchmarkWorker, 'args' => [job_id], 'queue' => 'benchmark')
+  job_id
+end
+
+deadline = started_at + timeout
+loop do
+  processed = Integer(redis.call('GET', SmokeBenchmark::COUNT_KEY) || 0)
+  results = Integer(redis.call('HLEN', SmokeBenchmark::RESULTS_KEY) || 0)
+  break if processed >= job_count && results >= job_count
+
+  if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+    abort "Timed out waiting for #{job_count} jobs (processed=#{processed}, results=#{results})"
+  end
+
+  sleep 0.1
+end
+
+elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at
+missing = job_ids.reject { |job_id| redis.call('HGET', SmokeBenchmark::RESULTS_KEY, job_id) == 'processed' }
+abort "Missing processed jobs: #{missing.join(', ')}" unless missing.empty?
+
+puts format('Benchmark passed: %<jobs>d jobs in %<seconds>.3f seconds (%<rate>.2f jobs/sec)',
+            jobs: job_count, seconds: elapsed, rate: job_count / elapsed)

data/smoke_test/benchmark/connection_pool_server.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require 'connection_pool'
+require 'redis-client'
+require 'sidekiq'
+require_relative 'worker'
+
+module SmokeBenchmark
+  # Connection-pool adapter with the same Redis health probe as the Ratomic run.
+  class ValidatedConnectionPool
+    def initialize(url:, size:, timeout:)
+      @pool = ConnectionPool.new(size:, timeout:) do
+        RedisClient.config(url:).new_client
+      end
+    end
+
+    def with
+      @pool.with do |redis|
+        raise 'Redis health check failed' unless redis.call('PING') == 'PONG'
+
+        yield redis
+      end
+    end
+  end
+
+  # Sidekiq middleware that injects the connection_pool-backed resource wrapper.
+  class ConnectionPoolBenchmarkMiddleware
+    def initialize(options = nil, pool_name: nil, size: 4, timeout: 5, redis_url: nil)
+      options ||= {}
+      pool_name = options.fetch(:pool_name, pool_name)
+      size = options.fetch(:size, size)
+      timeout = options.fetch(:timeout, timeout)
+      redis_url = options.fetch(:redis_url, redis_url)
+      @pool_name = pool_name
+      @pool = ValidatedConnectionPool.new(url: redis_url, size:, timeout:)
+    end
+
+    def config=(config)
+      mutex = config.instance_variable_get(:@connection_pool_benchmark_mutex)
+      unless mutex
+        mutex = Mutex.new
+        config.instance_variable_set(:@connection_pool_benchmark_mutex, mutex)
+      end
+
+      runtimes = config.instance_variable_get(:@connection_pool_benchmark_runtimes)
+      unless runtimes
+        runtimes = {}
+        config.instance_variable_set(:@connection_pool_benchmark_runtimes, runtimes)
+      end
+
+      mutex.synchronize do
+        runtime = runtimes[@pool_name]
+        if runtime
+          @pool = runtime.instance_variable_get(:@pool)
+        else
+          runtimes[@pool_name] = self
+        end
+      end
+      @config = config
+    end
+
+    def call(job, _payload, _queue)
+      setter = "#{@pool_name}="
+      job.public_send(setter, @pool) if job.respond_to?(setter)
+      yield
+    end
+  end
+end
+
+redis_port = ENV.fetch('REDIS_PORT', '6379')
+redis_url = ENV.fetch('REDIS_URL', "redis://127.0.0.1:#{redis_port}/0").freeze
+
+Sidekiq.configure_server do |config|
+  config.redis = { url: redis_url }
+  config.server_middleware do |chain|
+    chain.add(
+      SmokeBenchmark::ConnectionPoolBenchmarkMiddleware,
+      pool_name: :redis_pool,
+      size: Integer(ENV.fetch('RATOMIC_POOL_SIZE', '4')),
+      timeout: Float(ENV.fetch('RATOMIC_POOL_TIMEOUT', '1')),
+      redis_url:
+    )
+  end
+end

data/smoke_test/benchmark/ractor_host_adapter.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+# Host-owned Ractor integration example using real Redis. The host creates and
+# joins Ractors; each Ractor constructs its own middleware runtime and owns its
+# Redis connection pool.
+
+require 'etc'
+require 'redis-client'
+require 'sidekiq'
+require 'sidekiq/ratomic/pool'
+
+RedisResource = Data.define(:ractor_index, :client) do
+  def call(...)
+    client.call(...)
+  end
+end
+RedisFactory = Data.define(:ractor_index, :url) do
+  def call
+    RedisResource.new(ractor_index, RedisClient.config(url:).new_client)
+  end
+end
+HostInput = Data.define(
+  :index, :threads, :jobs, :pool_size, :pool_timeout, :queue_capacity, :work_seconds,
+  :redis_url, :count_key, :results_key, :run_id
+)
+
+ractor_count = Integer(ENV.fetch('RACTOR_NATIVE_COUNT', Etc.nprocessors.to_s))
+threads_per_ractor = Integer(ENV.fetch('RACTOR_NATIVE_THREADS', '20'))
+pool_size = Integer(ENV.fetch('RATOMIC_POOL_SIZE', '20'))
+pool_timeout = Float(ENV.fetch('RATOMIC_POOL_TIMEOUT', '1'))
+queue_capacity = Integer(ENV.fetch('RACTOR_QUEUE_CAPACITY', (threads_per_ractor * 2).to_s))
+jobs_per_ractor = Integer(ENV.fetch('BENCHMARK_JOBS_PER_RACTOR', threads_per_ractor.to_s))
+work_seconds = Float(ENV.fetch('BENCHMARK_WORK_SECONDS', '0.05'))
+redis_url = ENV.fetch('REDIS_URL', 'redis://127.0.0.1:6380/0').freeze
+run_id = ENV.fetch('BENCHMARK_RUN_ID', Process.clock_gettime(Process::CLOCK_REALTIME, :nanosecond).to_s).freeze
+count_key = "sidekiq-ratomic-pool:host-ractor-benchmark:#{run_id}:processed".freeze
+results_key = "sidekiq-ratomic-pool:host-ractor-benchmark:#{run_id}:results".freeze
+
+configuration = [
+  [ractor_count, 'RACTOR_NATIVE_COUNT'],
+  [threads_per_ractor, 'RACTOR_NATIVE_THREADS'],
+  [pool_size, 'RATOMIC_POOL_SIZE'],
+  [queue_capacity, 'RACTOR_QUEUE_CAPACITY'],
+  [jobs_per_ractor, 'BENCHMARK_JOBS_PER_RACTOR']
+]
+configuration.each do |value, name|
+  raise ArgumentError, "#{name} must be positive" unless value.positive?
+end
+raise ArgumentError, 'RATOMIC_POOL_TIMEOUT must be non-negative' if pool_timeout.negative?
+raise ArgumentError, 'BENCHMARK_WORK_SECONDS must be non-negative' if work_seconds.negative?
+
+redis = RedisClient.config(url: redis_url).new_client
+redis.call('DEL', count_key, results_key)
+redis_info = redis.call('INFO', 'server')
+redis_version = redis_info.lines.filter_map do |line|
+  line.split(':', 2).last&.strip if line.start_with?('redis_version:')
+end.first || 'unknown'
+
+puts "Ruby: #{RUBY_DESCRIPTION}"
+puts "Sidekiq: #{Sidekiq::VERSION}"
+puts "Ratomic: #{Ratomic::VERSION}"
+puts "Redis: #{redis_version}"
+puts "Run ID: #{run_id}"
+puts "CPU cores visible to the benchmark: #{Etc.nprocessors}"
+puts "Redis URL: #{redis_url}"
+puts "Ractors: #{ractor_count}, threads per Ractor: #{threads_per_ractor}, " \
+     "pool size per Ractor: #{pool_size}, checkout timeout: #{pool_timeout}s"
+puts "Jobs: #{ractor_count * jobs_per_ractor}, work per job: #{work_seconds}s, " \
+     "queue capacity per Ractor: #{queue_capacity}"
+
+started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+ractors = ractor_count.times.map do |index| # rubocop:disable Metrics/BlockLength
+  input = Ractor.make_shareable(
+    HostInput.new(
+      index, threads_per_ractor, jobs_per_ractor, pool_size, pool_timeout, queue_capacity, work_seconds,
+      redis_url, count_key, results_key, run_id
+    )
+  )
+  Ractor.new(input) do |ractor_input| # rubocop:disable Metrics/BlockLength
+    factory = RedisFactory.new(ractor_input.index, ractor_input.redis_url)
+    validator = ->(resource) { resource.call('PING') == 'PONG' }
+    pool = Sidekiq::Ratomic::Pool.new(
+      pool_name: :redis_pool,
+      size: ractor_input.pool_size,
+      pool_timeout: ractor_input.pool_timeout,
+      validator:,
+      factory:
+    )
+    jobs = SizedQueue.new(ractor_input.queue_capacity)
+    metrics = { active: 0, max_active: 0, processed: 0, error: nil }
+    metrics_mutex = Mutex.new
+    cancelled = false
+
+    producer = Thread.new do
+      ractor_input.jobs.times do |job|
+        break if cancelled
+
+        jobs << job
+      end
+    rescue ClosedQueueError
+      nil
+    ensure
+      jobs.close
+    end
+
+    workers = ractor_input.threads.times.map do # rubocop:disable Metrics/BlockLength
+      Thread.new do
+        loop do
+          job = jobs.pop
+          break if job.nil? || cancelled
+
+          metrics_mutex.synchronize do
+            metrics[:active] += 1
+            metrics[:max_active] = [metrics[:max_active], metrics[:active]].max
+          end
+          begin
+            pool.with do |resource|
+              job_id = "#{ractor_input.run_id}-#{ractor_input.index}-#{job}"
+              resource.call('INCR', ractor_input.count_key)
+              resource.call('HSET', ractor_input.results_key, job_id, 'processed')
+              sleep ractor_input.work_seconds if ractor_input.work_seconds.positive?
+            end
+            metrics_mutex.synchronize { metrics[:processed] += 1 }
+          rescue StandardError => e
+            metrics_mutex.synchronize { metrics[:error] = "#{e.class}: #{e.message}" }
+            cancelled = true
+            jobs.close
+          ensure
+            metrics_mutex.synchronize { metrics[:active] -= 1 }
+          end
+        end
+      rescue ClosedQueueError
+        nil
+      end
+    end
+
+    workers.each(&:value)
+    producer.join
+    pool.close
+    metrics.merge(index: ractor_input.index, jobs: ractor_input.jobs, threads: ractor_input.threads)
+  end
+end
+
+results = ractors.map(&:value)
+elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at
+failures = results.filter_map { |result| result[:error] }
+processed = Integer(redis.call('GET', count_key) || 0)
+result_count = Integer(redis.call('HLEN', results_key) || 0)
+expected = ractor_count * jobs_per_ractor
+unless failures.empty? && processed == expected && result_count == expected
+  abort "Host-owned Ractor example failed: results=#{results.inspect}, processed=#{processed}, " \
+        "result_count=#{result_count}, expected=#{expected}"
+end
+
+puts format(
+  'Host-owned Ractor example passed: %<ractors>d Ractors × %<pool>d resources × %<threads>d threads, ' \
+  '%<jobs>d jobs in %<seconds>.3f seconds (%<rate>.2f jobs/sec), max active=%<active>d',
+  ractors: ractor_count, pool: pool_size, threads: threads_per_ractor, jobs: processed,
+  seconds: elapsed, rate: processed / elapsed, active: results.sum { |result| result[:max_active] }
+)
+puts "Per-Ractor results: #{results.inspect}"

data/smoke_test/benchmark/ractor_native.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require 'ratomic'
+require 'redis-client'
+
+RedisFactory = Data.define(:url) do
+  def call
+    RedisClient.config(url:).new_client
+  end
+end
+RactorInput = Data.define(:pool, :jobs, :threads, :work_seconds, :count_key, :results_key, :run_id, :index)
+
+ractor_count = Integer(ENV.fetch('RACTOR_NATIVE_COUNT', '4'))
+threads_per_ractor = Integer(ENV.fetch('RACTOR_NATIVE_THREADS', '20'))
+pool_size = Integer(ENV.fetch('RATOMIC_POOL_SIZE', '20'))
+pool_timeout = Float(ENV.fetch('RATOMIC_POOL_TIMEOUT', '1'))
+work_seconds = Float(ENV.fetch('BENCHMARK_WORK_SECONDS', '0.05'))
+job_count = Integer(ENV.fetch('BENCHMARK_JOB_COUNT', (ractor_count * threads_per_ractor).to_s))
+
+redis_url = ENV.fetch('REDIS_URL', 'redis://127.0.0.1:6379/0').freeze
+run_id = ENV.fetch('BENCHMARK_RUN_ID', Process.clock_gettime(Process::CLOCK_REALTIME, :nanosecond).to_s).freeze
+count_key = "sidekiq-ratomic-pool:ractor-benchmark:#{run_id}:processed".freeze
+results_key = "sidekiq-ratomic-pool:ractor-benchmark:#{run_id}:results".freeze
+redis = RedisClient.config(url: redis_url).new_client
+redis.call('DEL', count_key, results_key)
+
+factory = Ractor.make_shareable(RedisFactory.new(redis_url))
+pool = Ratomic::LocalPool.new(size: pool_size, timeout: pool_timeout, factory:)
+jobs_per_ractor = job_count / ractor_count
+unless jobs_per_ractor * ractor_count == job_count
+  raise ArgumentError, 'BENCHMARK_JOB_COUNT must divide evenly across Ractors'
+end
+
+started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+ractors = ractor_count.times.map do |ractor_index| # rubocop:disable Metrics/BlockLength
+  input = Ractor.make_shareable(
+    RactorInput.new(
+      pool, jobs_per_ractor, threads_per_ractor, work_seconds, count_key, results_key, run_id, ractor_index
+    )
+  )
+  Ractor.new(input) do |ractor_input| # rubocop:disable Metrics/BlockLength
+    local_pool = ractor_input.pool
+    local_jobs = ractor_input.jobs
+    local_thread_count = ractor_input.threads
+    local_work_seconds = ractor_input.work_seconds
+    processed_key = ractor_input.count_key
+    result_key = ractor_input.results_key
+    benchmark_run_id = ractor_input.run_id
+    index = ractor_input.index
+    jobs = Queue.new
+    local_jobs.times { |job_index| jobs << job_index }
+    threads = local_thread_count.times.map do
+      Thread.new do
+        loop do
+          job_index = begin
+            jobs.pop(true)
+          rescue ThreadError
+            break
+          end
+          job_id = "#{benchmark_run_id}-#{index}-#{job_index}"
+          local_pool.with do |redis_client|
+            raise 'Redis health check failed' unless redis_client.call('PING') == 'PONG'
+
+            redis_client.call('INCR', processed_key)
+            redis_client.call('HSET', result_key, job_id, 'processed')
+            sleep local_work_seconds if local_work_seconds.positive?
+          end
+        end
+      end
+    end
+    threads.each(&:value)
+    local_pool.close
+    [local_thread_count, local_jobs]
+  end
+end
+
+ractor_results = ractors.map(&:value)
+elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at
+processed = Integer(redis.call('GET', count_key) || 0)
+results = Integer(redis.call('HLEN', results_key) || 0)
+abort "Benchmark mismatch (processed=#{processed}, results=#{results}, expected=#{job_count})" unless
+  processed == job_count && results == job_count
+
+puts format(
+  'Ractor benchmark passed: %<ractors>d Ractors × %<pool>d resources × %<threads>d threads, ' \
+  '%<jobs>d jobs in %<seconds>.3f seconds (%<rate>.2f jobs/sec)',
+  ractors: ractor_results.size, pool: pool_size, threads: threads_per_ractor, jobs: job_count,
+  seconds: elapsed, rate: job_count / elapsed
+)

data/smoke_test/benchmark/server.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative '../server'
+require_relative 'worker'

data/smoke_test/benchmark/worker.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module SmokeBenchmark
+  COUNT_KEY = 'sidekiq-ratomic-pool:benchmark:processed'
+  RESULTS_KEY = 'sidekiq-ratomic-pool:benchmark:results'
+
+  # Benchmark job that performs Redis work through the injected pool.
+  class RedisBenchmarkWorker
+    include Sidekiq::Job
+
+    sidekiq_options queue: 'benchmark', retry: 0
+
+    attr_accessor :redis_pool
+
+    def perform(job_id)
+      redis_pool.with do |redis|
+        redis.call('INCR', COUNT_KEY)
+        redis.call('HSET', RESULTS_KEY, job_id, 'processed')
+        work_seconds = Float(ENV.fetch('BENCHMARK_WORK_SECONDS', '0.05'))
+        sleep work_seconds if work_seconds.positive?
+      end
+    end
+  end
+end

data/smoke_test/server.rb

@@ -21,6 +21,7 @@ Sidekiq.configure_server do |config|
       Sidekiq::Ratomic::Pool,
       pool_name: :redis_pool,
       size: Integer(ENV.fetch('RATOMIC_POOL_SIZE', '4')),
+      pool_timeout: Float(ENV.fetch('RATOMIC_POOL_TIMEOUT', '1')),
       max_retries: 3,
       retry_delay: 0.05,
       cb_threshold: 5,

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sidekiq-ratomic-pool
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Ken C. Demanawa
@@ -40,6 +40,12 @@ files:
 - lib/sidekiq/ratomic/pool/version.rb
 - lib/sidekiq_ratomic_pool.rb
 - sig/sidekiq/ratomic/pool.rbs
+- smoke_test/benchmark/client.rb
+- smoke_test/benchmark/connection_pool_server.rb
+- smoke_test/benchmark/ractor_host_adapter.rb
+- smoke_test/benchmark/ractor_native.rb
+- smoke_test/benchmark/server.rb
+- smoke_test/benchmark/worker.rb
 - smoke_test/client.rb
 - smoke_test/server.rb
 - smoke_test/worker.rb