cdc-parallel 0.2.0 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6e16d6352e78132e2e0f488542b17117bda8733ca15b3117f8151b6acbfc3567
-  data.tar.gz: 3e28c6c37d5078696ab334f5c8b15409172bebb8102747c2e7558f0089d4ad64
+  metadata.gz: a51d304d55079509a1c2056573a9f4764924573b9a13eb1dbeda89ac94d57836
+  data.tar.gz: 4e154536aaca3d801d4affe02e424f332c6a1a37b738ee70cc8fea5f335645fd
 SHA512:
-  metadata.gz: 4e71ef2eeda63a9d6f6c59d49ba140b73a62d0e37894e168060a4c796f28a7d6790b37b891c7188fff78de1e843386c0f892f0720ba3de16ea9bfe198e719382
-  data.tar.gz: de5eb4cb7861e263402305e361d4ac49d335d9b657562cca93544c64f34f76646289212647506c87f4d6ef7eb5ec586cbb58596ad9427f8becb99ca1af82127c
+  metadata.gz: c3002bfcd3914510fc39e7621fba99a7868303d24f8c8e5b849d40c653f73355b9926636ed6bb31754f2f028d65af325207eb89466923bc413eb8e44538730e7
+  data.tar.gz: 686ef1d6c0759d8ebedbd18e7109a4ac22008e8a0501faab31db8440bef3cf1127f79b076ce46fd3d8eec46f6e524e0ac6a75b1d3e0cefbc2f5ab151e99110b8

data/CHANGELOG.md

@@ -4,6 +4,31 @@ 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.
 
+ ## [0.2.2] - 2026-06-03
+
+  ### Changed
+
+  - Improved processor pool shutdown so workers are signaled and confirmed stopped where practical.
+  - Updated transaction processing so partial event failures fail the transaction result while preserving per-event results.
+  - Added CI validation for RBS signatures.
+
+  ### Added
+
+  - Added regression coverage for shutdown after processed and pending work.
+  - Added regression coverage for timeout-bounded shutdown behavior.
+  - Added regression coverage for `process_many([])` returning a clean empty result.
+  - Added transaction pool coverage for successful and partially failed transactions.
+
+## [0.2.1] - 2026-06-03
+
+### Added
+
+  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

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

@@ -8,7 +8,7 @@ module CDC
     # 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
+    class ProcessorPool # rubocop:disable Metrics/ClassLength
       # @param processor [CDC::Core::Processor]
       # @param size [Integer]
       # @param timeout [Float, nil]
@@ -63,6 +63,13 @@ module CDC
 
         @shutdown = true
 
+        signal_workers
+        wait_for_workers
+      end
+
+      private
+
+      def signal_workers
         @workers.each do |worker|
           worker.send(nil)
         rescue Ractor::ClosedError
@@ -70,7 +77,26 @@ module CDC
         end
       end
 
-      private
+      def wait_for_workers
+        if @configuration.timeout
+          wait_for_workers_with_timeout
+        else
+          @workers.each(&:join)
+        end
+      end
+
+      def wait_for_workers_with_timeout
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + @configuration.timeout
+
+        @workers.each do |worker|
+          remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          break unless remaining.positive?
+
+          ::Timeout.timeout(remaining, TimeoutError) { worker.join }
+        rescue TimeoutError
+          break
+        end
+      end
 
       def validate_processor!(processor)
         return if processor.class.respond_to?(:ractor_safe?) &&
@@ -80,7 +106,7 @@ module CDC
               "#{processor.class} must declare ractor_safe!"
       end
 
-      def build_worker(processor)
+      def build_worker(processor) # rubocop:disable Metrics/MethodLength
         ::Ractor.new(processor) do |safe_processor|
           loop do
             message = ::Ractor.receive
@@ -96,7 +122,11 @@ module CDC
               CDC::Parallel::ResultCollector.worker_failure(e)
             end
 
-            reply_port << [index, response]
+            begin
+              reply_port << [index, response]
+            rescue Ractor::ClosedError
+              # The caller may have timed out and closed the reply port.
+            end
           end
         end
       end
@@ -112,14 +142,50 @@ module CDC
 
       def collect_results(reply_port, count)
         results = Array.new(count)
+        return results.freeze if count.zero?
 
-        count.times do
+        if @configuration.timeout
+          collect_results_with_timeout(reply_port, results)
+        else
+          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
 end

data/lib/cdc/parallel/transaction_pool.rb

@@ -16,8 +16,12 @@ module CDC
       # @param transaction [CDC::Core::TransactionEnvelope]
       # @return [CDC::Core::ProcessorResult]
       def process(transaction)
-        results = transaction.events.map { |event| @processor_pool.process(event) }.freeze
-        ResultCollector.normalize(results)
+        results = @processor_pool.process_many(transaction.events).freeze
+        failure = results.find(&:failure?)
+
+        return CDC::Core::ProcessorResult.failure(failure.error, event: results) if failure
+
+        CDC::Core::ProcessorResult.success(results)
       end
 
       # Shut down worker resources.

data/lib/cdc/parallel/version.rb

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

data/lib/cdc/parallel.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "etc"
+require "timeout"
 
 require_relative "parallel/version"
 require_relative "parallel/errors"

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.
       #
@@ -32,9 +37,25 @@ module CDC
 
       private
 
+      def signal_workers: () -> untyped
+
+      def wait_for_workers: () -> untyped
+
+      def wait_for_workers_with_timeout: () -> untyped
+
       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/cdc_core.rbs

@@ -2,7 +2,7 @@ module CDC
   module Core
     class ProcessorResult
       def self.success: (untyped event) -> ProcessorResult
-      def self.failure: (untyped error) -> ProcessorResult
+      def self.failure: (untyped error, ?event: untyped) -> ProcessorResult
     end
 
     class ChangeEvent
@@ -11,4 +11,4 @@ module CDC
     class TransactionEnvelope
     end
   end
-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.2.0
+  version: 0.2.2
 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