cdc-parallel 0.1.1 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0f5c66df35f175cac43e88bae1fec2eba6d381d2bcb41940445863a9bb726032
-  data.tar.gz: 975b651448c205b7458b2c381e5ae93a248c64323e019db5cae73eb880130477
+  metadata.gz: 72b3b33568a37fa04b270edad8511a446703f115d78d86c2347c6af2e4be76a0
+  data.tar.gz: e044e42d90f11b6b75b946ef0f1b1725f2810056be353a56342a908c139eb91c
 SHA512:
-  metadata.gz: 247be6f8016f3d4ffda9e13dd5c61c1359d1ccf26947ce56674e755d296f329172fd86b85a6386eba08d4c48efb24b082bf3c6f03cdfbf6ce28f4103dc28984c
-  data.tar.gz: 28009df5732c2679e4e433508fe8f47dc69037c7bd3416b05d9b4d5165229c2175c42dcd0dc4fe743daacfbfd76a5b4f4b6b02d10421debaf249ab3a06577256
+  metadata.gz: 3780fa1a616b33e824cff4f6c7f0ec8402085e5a742abbaa45082d1dc8ce6c7be04bd462aa78e4afcb61f7f9a3b0adab54ed4e47f972633c12348d57e65a632f
+  data.tar.gz: 01ae9a18f4d8a6bab6c5f7e71333c38475a1930bdce6326e41bc9376100e74800cb850b22b8fda1de9638a2e78be3094a27bfd1b6592a6e868554ce933b471af

data/CHANGELOG.md

@@ -4,11 +4,45 @@ All notable changes to this project will be documented in this file.
 
 The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
 
-## [Unreleased]
+## [0.2.1] - 2026-06-03
 
 ### Added
 
-- Placeholder for future development.
+  v0.2.1 - Correctness and reliability patch
+
+  - Enforced processor timeout handling.
+  - Fixed transaction partial-failure behavior.
+  - Added regression coverage for hung processors and transaction failure cases.
+
+## [0.2.0] - 2026-06-03
+
+### Added
+
+- Pre-warmed persistent Ractor worker pool implementation.
+- `ProcessorPool#process_many` for batched dispatch.
+- Tiny workload benchmark for dispatch overhead analysis.
+- CPU-bound workload benchmark for throughput analysis.
+- Batch workload benchmark for CDC-style event processing.
+- Performance test suite guarded by `CDC_PARALLEL_PERFORMANCE_TESTS=1`.
+- Reusable benchmark Docker image.
+- `benchmark:processor_pool` Rake task.
+- `benchmark:docker_build` Rake task.
+- `benchmark:docker_run` Rake task.
+- Benchmark documentation and reproducibility guidance.
+
+### Changed
+
+- Processor workers are now initialized once and reused for the lifetime of the pool.
+- Benchmark methodology updated to measure pre-warmed worker execution.
+- README updated with benchmark execution instructions and example results.
+
+### Performance
+
+Local benchmark results on Ruby 4.0.5 (4 workers) demonstrated measurable throughput improvements for CPU-bound workloads using pre-warmed worker pools compared to serial execution.
+
+Benchmark results vary by hardware, operating system, Ruby version, and workload characteristics. Users are encouraged to reproduce results on their own systems using the included benchmark suite.
+
+
 
 ## [0.1.0] - 2026-05-31
 

data/README.md

@@ -161,3 +161,106 @@ The default `test` task runs unit, integration, and behavior tests. Performance
 ## License
 
 MIT.
+
+
+## Benchmarking
+
+`cdc-parallel` includes reproducible benchmarks that compare serial processor execution against the pre-warmed Ractor worker pool.
+
+The benchmark focuses on three workload categories:
+
+| Workload | Purpose                                         |
+| -------- | ----------------------------------------------- |
+| tiny     | Measure dispatch overhead                       |
+| cpu      | Measure CPU-bound processing throughput         |
+| batch    | Measure batched CDC event processing throughput |
+
+### Running Benchmarks
+
+Tiny workload:
+
+```bash
+BENCHMARK_WORKLOAD=tiny \
+bundle exec rake benchmark:processor_pool
+```
+
+CPU-bound workload:
+
+```bash
+BENCHMARK_WORKLOAD=cpu \
+BENCHMARK_CPU_ROUNDS=5000 \
+bundle exec rake benchmark:processor_pool
+```
+
+Batch workload:
+
+```bash
+BENCHMARK_WORKLOAD=batch \
+BENCHMARK_BATCH_SIZE=10000 \
+bundle exec rake benchmark:processor_pool
+```
+
+### Benchmark Docker Image
+
+Build and run the reusable Docker image:
+
+```bash
+bundle exec rake benchmark:docker_build
+bundle exec rake benchmark:docker_run
+```
+
+Or run the image directly after it is published to GitHub Container Registry:
+
+```bash
+docker run --rm ghcr.io/kanutocd/cdc-parallel-benchmark:main
+```
+
+The benchmark image is intended to become the shared performance validation
+pattern across CDC Ecosystem gems, enabling reproducible benchmark execution
+locally, in CI, and across different development environments.
+
+### Example Result
+
+Environment:
+
+* Ruby 4.0.5
+* x86_64 Linux
+* 4 workers
+
+CPU workload (`BENCHMARK_CPU_ROUNDS=5000`):
+
+```json
+{
+  "serial": {
+    "events_per_second": 120.26
+  },
+  "parallel": {
+    "events_per_second": 250.15
+  },
+  "ratio": {
+    "parallel_to_serial": 2.08
+  }
+}
+```
+
+### Interpretation
+
+A ratio greater than `1.0` indicates that the pre-warmed Ractor worker pool outperformed serial execution.
+
+```text
+ratio > 1.0  => parallel faster
+ratio = 1.0  => equivalent
+ratio < 1.0  => serial faster
+```
+
+### Reproducibility
+
+Benchmark results vary depending on:
+
+* CPU model
+* Core count
+* Operating system
+* Ruby version
+* Background system activity
+
+The benchmark suite is provided so that users can reproduce and validate results on their own hardware.

data/lib/cdc/parallel/configuration.rb

@@ -12,6 +12,8 @@ module CDC
       def initialize(size: Etc.nprocessors, timeout: nil)
         raise ArgumentError, "size must be an Integer" unless size.is_a?(Integer)
         raise ArgumentError, "size must be greater than zero" unless size.positive?
+        raise ArgumentError, "timeout must be numeric" unless timeout.nil? || timeout.is_a?(Numeric)
+        raise ArgumentError, "timeout must be greater than zero" if timeout && !timeout.positive?
 
         super
         ::Ractor.make_shareable(self)

data/lib/cdc/parallel/processor_pool.rb

@@ -2,13 +2,13 @@
 
 module CDC
   module Parallel
-    # Executes one Ractor-safe processor in isolated Ractor workers.
+    # Executes one Ractor-safe processor in pre-warmed persistent Ractor workers.
     #
-    # This v0.1 implementation intentionally uses one-shot worker Ractors for
-    # deterministic synchronous semantics while preserving the public pool API.
-    # The parallel-pool dependency is kept as the runtime foundation for later
-    # async/throughput-focused versions.
-    class ProcessorPool
+    # Workers are created during initialization and reused for every dispatch.
+    # This pays Ractor startup cost once, keeps workers alive after processor
+    # failures, and provides both synchronous single-item processing and batched
+    # dispatch for throughput-oriented benchmarks and runtimes.
+    class ProcessorPool # rubocop:disable Metrics/ClassLength
       # @param processor [CDC::Core::Processor]
       # @param size [Integer]
       # @param timeout [Float, nil]
@@ -18,47 +18,147 @@ module CDC
 
         @processor = ::Ractor.make_shareable(processor)
         @configuration = Configuration.new(size:, timeout:)
+        @workers = Array.new(@configuration.size) do
+          build_worker(@processor)
+        end.freeze
+
+        @next_worker = 0
         @shutdown = false
       end
 
-      # Process one ChangeEvent.
+      # Process one work item synchronously.
       #
-      # @param event [CDC::Core::ChangeEvent]
+      # @param item [Object]
       # @return [CDC::Core::ProcessorResult]
-      def process(event)
+      def process(item)
+        process_many([item]).fetch(0)
+      end
+
+      # Process many work items using the pre-warmed worker pool.
+      #
+      # Results are returned in the same order as the supplied work items.
+      #
+      # @param items [Array<Object>]
+      # @return [Array<CDC::Core::ProcessorResult>]
+      def process_many(items)
         raise ShutdownError, "processor pool has been shut down" if @shutdown
 
-        work = ::Ractor.make_shareable(event)
-        worker = ::Ractor.new(@processor, work) do |processor, item|
-          CDC::Parallel::ResultCollector.normalize(processor.process(item))
-        rescue StandardError => e
-          CDC::Parallel::ResultCollector.worker_failure(e)
+        work_items = items.map { |item| ::Ractor.make_shareable(item) }
+        reply_port = ::Ractor::Port.new
+
+        work_items.each_with_index do |item, index|
+          next_worker.send([index, item, reply_port])
         end
 
-        ResultCollector.normalize(take(worker))
+        collect_results(reply_port, work_items.length)
+      ensure
+        reply_port&.close
       end
 
       # Shut down the pool.
       #
       # @return [void]
       def shutdown
+        return if @shutdown
+
         @shutdown = true
+
+        @workers.each do |worker|
+          worker.send(nil)
+        rescue Ractor::ClosedError
+          # Already stopped.
+        end
       end
 
       private
 
       def validate_processor!(processor)
-        return if processor.class.respond_to?(:ractor_safe?) && processor.class.ractor_safe?
+        return if processor.class.respond_to?(:ractor_safe?) &&
+                  processor.class.ractor_safe?
 
-        raise UnsafeProcessorError, "#{processor.class} must declare ractor_safe!"
+        raise UnsafeProcessorError,
+              "#{processor.class} must declare ractor_safe!"
       end
 
-      def take(worker)
-        if worker.respond_to?(:value)
-          worker.value
+      def build_worker(processor) # rubocop:disable Metrics/MethodLength
+        ::Ractor.new(processor) do |safe_processor|
+          loop do
+            message = ::Ractor.receive
+            break if message.nil?
+
+            index, item, reply_port = message
+
+            response = begin
+              CDC::Parallel::ResultCollector.worker_success(
+                safe_processor.process(item)
+              )
+            rescue StandardError => e
+              CDC::Parallel::ResultCollector.worker_failure(e)
+            end
+
+            begin
+              reply_port << [index, response]
+            rescue Ractor::ClosedError
+              # The caller may have timed out and closed the reply port.
+            end
+          end
+        end
+      end
+
+      def next_worker
+        worker = @workers[@next_worker]
+
+        @next_worker += 1
+        @next_worker = 0 if @next_worker >= @workers.length
+
+        worker
+      end
+
+      def collect_results(reply_port, count)
+        results = Array.new(count)
+        return results.freeze if count.zero?
+
+        if @configuration.timeout
+          collect_results_with_timeout(reply_port, results)
         else
-          worker.take
+          collect_results_without_timeout(reply_port, results)
+        end
+      end
+
+      def collect_results_without_timeout(reply_port, results)
+        results.length.times do
+          index, response = reply_port.receive
+          results[index] = ResultCollector.normalize(response)
+        end
+
+        results.freeze
+      end
+
+      def collect_results_with_timeout(reply_port, results)
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + @configuration.timeout
+
+        results.length.times do
+          remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          return timeout_results(results) unless remaining.positive?
+
+          index, response = ::Timeout.timeout(remaining, TimeoutError) { reply_port.receive }
+          results[index] = ResultCollector.normalize(response)
+        rescue TimeoutError
+          return timeout_results(results)
         end
+
+        results.freeze
+      end
+
+      def timeout_results(results)
+        missing = results.count(&:nil?)
+        timeout_error = TimeoutError.new(
+          "processor pool timed out after #{@configuration.timeout} seconds waiting for #{missing} result(s)"
+        )
+
+        results.map do |result|
+          result || CDC::Core::ProcessorResult.failure(timeout_error)
+        end.freeze
       end
     end
   end

data/lib/cdc/parallel/result_collector.rb

@@ -6,6 +6,14 @@ module CDC
     class ResultCollector
       FAILURE_MARKER = :__cdc_parallel_failure__
 
+      # Build a shareable success payload that can safely cross a Ractor boundary.
+      #
+      # @param value [Object]
+      # @return [Object]
+      def self.worker_success(value)
+        ::Ractor.make_shareable(value)
+      end
+
       # Build a shareable failure payload that can safely cross a Ractor boundary.
       #
       # @param error [Exception]

data/lib/cdc/parallel/version.rb

@@ -3,6 +3,6 @@
 module CDC
   module Parallel
     # Current cdc-parallel version.
-    VERSION = "0.1.1"
+    VERSION = "0.2.1"
   end
 end

data/lib/cdc/parallel.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require "etc"
-require "ractor-pool"
+require "timeout"
 
 require_relative "parallel/version"
 require_relative "parallel/errors"
@@ -13,7 +13,7 @@ require_relative "parallel/router"
 require_relative "parallel/runtime"
 
 module CDC
-  # Optional high-throughput Ractor runtime for cdc-core processors.
+  # Optional parallel Change Data Capture runtime for cdc-core processors.
   module Parallel
   end
 end

data/sig/cdc/parallel/processor_pool.rbs

@@ -1,16 +1,15 @@
 module CDC
   module Parallel
-    # Executes one Ractor-safe processor in isolated Ractor workers.
-    #
-    # This v0.1 implementation intentionally uses one-shot worker Ractors for
-    # deterministic synchronous semantics while preserving the public pool API.
-    # The parallel-pool dependency is kept as the runtime foundation for later
-    # async/throughput-focused versions.
+    # Executes one Ractor-safe processor in pre-warmed persistent Ractor workers.
     class ProcessorPool
       @processor: untyped
 
       @configuration: untyped
 
+      @workers: untyped
+
+      @next_worker: Integer
+
       @shutdown: untyped
 
       # @param processor [CDC::Core::Processor]
@@ -19,11 +18,17 @@ module CDC
       # @return [void]
       def initialize: (processor: untyped, ?size: untyped, ?timeout: untyped?) -> void
 
-      # Process one ChangeEvent.
+      # Process one work item synchronously.
       #
-      # @param event [CDC::Core::ChangeEvent]
+      # @param item [Object]
       # @return [CDC::Core::ProcessorResult]
-      def process: (untyped event) -> untyped
+      def process: (untyped item) -> untyped
+
+      # Process many work items using the pre-warmed worker pool.
+      #
+      # @param items [Array<Object>]
+      # @return [Array<CDC::Core::ProcessorResult>]
+      def process_many: (untyped items) -> untyped
 
       # Shut down the pool.
       #
@@ -34,7 +39,17 @@ module CDC
 
       def validate_processor!: (untyped processor) -> (nil | untyped)
 
-      def take: (untyped worker) -> untyped
+      def build_worker: (untyped processor) -> untyped
+
+      def next_worker: () -> untyped
+
+      def collect_results: (untyped reply_port, Integer count) -> untyped
+
+      def collect_results_without_timeout: (untyped reply_port, untyped results) -> untyped
+
+      def collect_results_with_timeout: (untyped reply_port, untyped results) -> untyped
+
+      def timeout_results: (untyped results) -> untyped
     end
   end
 end

data/sig/cdc/parallel/result_collector.rbs

@@ -4,6 +4,12 @@ module CDC
     class ResultCollector
       FAILURE_MARKER: :__cdc_parallel_failure__
 
+      # Build a shareable success payload that can safely cross a Ractor boundary.
+      #
+      # @param value [Object]
+      # @return [Object]
+      def self.worker_success: (untyped value) -> untyped
+
       # Build a shareable failure payload that can safely cross a Ractor boundary.
       #
       # @param error [Exception]

data/sig/cdc/parallel/version.rbs

@@ -1,6 +1,6 @@
 module CDC
   module Parallel
     # Current cdc-parallel version.
-    VERSION: "0.1.0"
+    VERSION: "0.2.0"
   end
 end

data/sig/shims/timeout.rbs

@@ -0,0 +1,3 @@
+module Timeout
+  def self.timeout: (untyped sec, untyped klass) { () -> untyped } -> untyped
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cdc-parallel
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.1
 platform: ruby
 authors:
 - Ken C. Demanawa
@@ -73,6 +73,7 @@ files:
 - sig/shims/cdc_core.rbs
 - sig/shims/data_define.rbs
 - sig/shims/etc.rbs
+- sig/shims/timeout.rbs
 homepage: https://kanutocd.github.io/cdc-parallel/
 licenses:
 - MIT