cdc-parallel 0.2.2 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a51d304d55079509a1c2056573a9f4764924573b9a13eb1dbeda89ac94d57836
-  data.tar.gz: 4e154536aaca3d801d4affe02e424f332c6a1a37b738ee70cc8fea5f335645fd
+  metadata.gz: 727373877c3c90e65e65ec4bbb5f5312b7e0d15d879af54402fa6752ac730aa0
+  data.tar.gz: cd2701bf5e93f5ef825f4b2e95a015dfbbb214bb14cb3f095a65d499aeaf9f28
 SHA512:
-  metadata.gz: c3002bfcd3914510fc39e7621fba99a7868303d24f8c8e5b849d40c653f73355b9926636ed6bb31754f2f028d65af325207eb89466923bc413eb8e44538730e7
-  data.tar.gz: 686ef1d6c0759d8ebedbd18e7109a4ac22008e8a0501faab31db8440bef3cf1127f79b076ce46fd3d8eec46f6e524e0ac6a75b1d3e0cefbc2f5ab151e99110b8
+  metadata.gz: 33e6152dfaf7fdeda19853229519f2154b6ec39cb87b3c074dea0658e94eb65156d11d8e7ce11d0c3560dae678fe196dc1cc99a4f6fb4c6d712f8b84be7ad274
+  data.tar.gz: 9999fdf8a4e05694f506b1a4f6e6db9679bc0da09d47b8c67513959d8467ead0fce0b26245b158c3101c8467110ed29af2aefeb4bc13c27d95ac76e38920e449

data/CHANGELOG.md

@@ -4,30 +4,59 @@ 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
+## Unreleased
 
-  ### Changed
+No unreleased changes.
 
-  - 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.
+## [0.2.3] - 2026-06-03
 
-  ### Added
+### Added
+
+- Added Port-native `Ractor::Port` worker inbox dispatch for the pre-warmed processor pool.
+- Added concurrent threaded caller regression coverage for `ProcessorPool#process_many`.
+- Added worker inbox boot verification coverage.
+- Added multi-trial processor-pool benchmark reporting with min, median, max, and p95 distributions.
+- Added minimum measurement duration support for benchmark trials.
+- Added worker-count sweep support through `BENCHMARK_WORKER_COUNTS`.
+- Added benchmark comparison across serial execution, repeated `ProcessorPool#process`, and batched `ProcessorPool#process_many`.
+- Added benchmark environment metadata for Ruby, platform, host, CPU count, and uname details.
+- Added detailed benchmark methodology and report documentation under `benchmark/README.md`.
+
+### Changed
+
+- Updated worker dispatch to send work through worker-owned inbox ports instead of direct worker messages.
+- Synchronized dispatch and shutdown with a mutex so multiple Ruby threads can submit work safely.
+- Updated processor pool RBS signatures for worker inboxes and Port-native dispatch helpers.
+- Expanded README documentation for the worker dispatch model.
+- Updated README benchmark guidance to point to the detailed benchmark report documentation.
+- Updated benchmark ratio reporting to compare median throughput against serial execution.
+
+## [0.2.2] - 2026-06-03
 
-  - 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.
+### 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.
 
-  - Enforced processor timeout handling.
-  - Fixed transaction partial-failure behavior.
-  - Added regression coverage for hung processors and transaction failure cases.
+### Changed
+
+- Released a correctness and reliability patch.
 
 ## [0.2.0] - 2026-06-03
 
@@ -57,7 +86,12 @@ Local benchmark results on Ruby 4.0.5 (4 workers) demonstrated measurable throug
 
 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.1] - 2026-06-03
+
+No code changes.
 
+Improves RubyGems metadata and documentation wording to
+explicitly identify CDC as Change Data Capture.
 
 ## [0.1.0] - 2026-05-31
 
@@ -77,10 +111,3 @@ Benchmark results vary by hardware, operating system, Ruby version, and workload
 - Added Minitest suite.
 - Added README and example.
 - Added CI and release workflows.
-
-## [0.1.1] - 2026-06-03
-
-No code changes.
-
-Improves RubyGems metadata and documentation wording to
-explicitly identify CDC as Change Data Capture.

data/README.md

@@ -2,7 +2,6 @@
 
 [![Gem Version](https://badge.fury.io/rb/cdc-parallel.svg)](https://badge.fury.io/rb/cdc-parallel)
 [![CI](https://github.com/kanutocd/cdc-parallel/workflows/CI/badge.svg)](https://github.com/kanutocd/cdc-parallel/actions)
-[![Coverage Status](https://codecov.io/gh/kanutocd/cdc-parallel/branch/main/graph/badge.svg)](https://codecov.io/gh/kanutocd/cdc-parallel)
 [![Ruby Version](https://img.shields.io/badge/ruby-%3E%3D%204.0-ruby.svg)](https://www.ruby-lang.org/en/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
@@ -82,6 +81,39 @@ Unsafe processors raise:
 CDC::Parallel::UnsafeProcessorError
 ```
 
+## Concurrency Contract
+
+`CDC::Parallel::ProcessorPool` accepts submissions from multiple Ruby threads.
+Dispatch state is synchronized inside the pool, while processor execution occurs
+inside isolated Ruby 4 Ractors.
+
+Workers own their `Ractor::Port` inboxes. The pool sends work to those inboxes,
+and workers send results back to a caller-owned reply port.
+
+```text
+Caller Thread A ─┐
+Caller Thread B ─┼─> ProcessorPool
+Caller Thread C ─┘        │
+                          │ synchronized dispatch
+                          ▼
+                +-------------------+
+                | worker selection  |
+                +-------------------+
+                  │       │       │
+                  ▼       ▼       ▼
+            inbox port inbox port inbox port
+                  │       │       │
+                  ▼       ▼       ▼
+            Ractor 1  Ractor 2  Ractor 3
+                  │       │       │
+                  └───┬───┴───┬───┘
+                      ▼       ▼
+             caller-owned   reply port
+                      │
+                      ▼
+             ordered ProcessorResult[]
+```
+
 ## What Belongs Here
 
 - Ractor processor execution
@@ -175,7 +207,10 @@ The benchmark focuses on three workload categories:
 | cpu      | Measure CPU-bound processing throughput         |
 | batch    | Measure batched CDC event processing throughput |
 
-### Running Benchmarks
+See [benchmark/README.md](benchmark/README.md) for the full benchmark methodology,
+configuration reference, report schema, and interpretation guidance.
+
+### Quick Start
 
 Tiny workload:
 
@@ -200,6 +235,23 @@ BENCHMARK_BATCH_SIZE=10000 \
 bundle exec rake benchmark:processor_pool
 ```
 
+Worker-count sweep:
+
+```bash
+BENCHMARK_WORKLOAD=cpu \
+BENCHMARK_WORKER_COUNTS=1,2,4 \
+bundle exec rake benchmark:processor_pool
+```
+
+Credibility controls:
+
+```bash
+BENCHMARK_TRIALS=7 \
+BENCHMARK_MIN_DURATION=0.25 \
+BENCHMARK_ITERATIONS=1000 \
+bundle exec rake benchmark:processor_pool
+```
+
 ### Benchmark Docker Image
 
 Build and run the reusable Docker image:
@@ -218,49 +270,3 @@ 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

@@ -2,13 +2,36 @@
 
 module CDC
   module Parallel
-    # Immutable configuration for Ractor runtimes.
+    # Immutable configuration shared by cdc-parallel runtime objects.
     #
-    # @!attribute size
-    #   @return [Integer] worker count.
-    # @!attribute timeout
-    #   @return [Float, nil] optional wait timeout in seconds.
+    # `Configuration` validates worker sizing and timeout values at construction
+    # time, freezes the resulting data object through `Data.define`, and makes
+    # the instance shareable so it is safe to retain around Ractor-oriented
+    # runtime objects.
+    #
+    # @example Default configuration
+    #   config = CDC::Parallel::Configuration.new
+    #   config.size    #=> Etc.nprocessors
+    #   config.timeout #=> nil
+    #
+    # @example Explicit worker count and timeout
+    #   config = CDC::Parallel::Configuration.new(size: 4, timeout: 5)
+    #
+    # @!attribute [r] size
+    #   @return [Integer] Number of worker Ractors to boot.
+    # @!attribute [r] timeout
+    #   @return [Numeric, nil] Optional wait timeout in seconds.
+    # @api public
     class Configuration < Data.define(:size, :timeout)
+      # Create a validated runtime configuration.
+      #
+      # @param size [Integer]
+      #   Worker count. Must be greater than zero.
+      # @param timeout [Numeric, nil]
+      #   Optional timeout in seconds. Must be greater than zero when provided.
+      # @raise [ArgumentError]
+      #   Raised when `size` or `timeout` is invalid.
+      # @return [void]
       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?

data/lib/cdc/parallel/errors.rb

@@ -2,22 +2,69 @@
 
 module CDC
   module Parallel
-    # Base cdc-parallel error.
+    # Base error for all cdc-parallel-specific failures.
+    #
+    # Rescue this class when callers want to handle any failure raised directly
+    # by the parallel runtime layer.
+    #
+    # @api public
     class Error < StandardError; end
 
     # Raised when a processor has not declared itself Ractor-safe.
+    #
+    # Processors must opt in with `ractor_safe!` before they can be used by
+    # {ProcessorPool}, {TransactionPool}, or {Runtime}. This prevents accidental
+    # movement of mutable or otherwise unsafe processor objects across Ractor
+    # boundaries.
+    #
+    # @api public
     class UnsafeProcessorError < Error; end
 
-    # Raised when work is submitted after shutdown.
+    # Raised when work is submitted after a pool or runtime has been shut down.
+    #
+    # @api public
     class ShutdownError < Error; end
 
-    # Raised when the runtime receives an unsupported work item.
+    # Raised when the runtime receives an unsupported work item shape.
+    #
+    # `cdc-parallel` accepts normalized `CDC::Core::ChangeEvent` and
+    # `CDC::Core::TransactionEnvelope` objects. Source-specific payloads must be
+    # normalized by a source adapter before they reach this runtime layer.
+    #
+    # @api public
     class UnsupportedWorkItemError < Error; end
 
-    # Raised when processor execution fails inside a worker Ractor.
+    # Represents an exception raised inside a worker Ractor.
+    #
+    # Worker exceptions are serialized before they cross the Ractor boundary and
+    # reconstructed as `ProcessorExecutionError` instances by
+    # {ResultCollector.normalize}. The original exception class name, message,
+    # and backtrace are exposed for diagnostics.
+    #
+    # @example Inspecting the original worker exception
+    #   result = runtime.process(event)
+    #   if result.failure?
+    #     error = result.error
+    #     error.original_class
+    #     error.original_message
+    #   end
+    #
+    # @attr_reader original_class [String] original exception class name.
+    # @attr_reader original_message [String] original exception message.
+    # @attr_reader original_backtrace [Array<String>] original exception backtrace.
+    # @api public
     class ProcessorExecutionError < Error
       attr_reader :original_class, :original_message, :original_backtrace
 
+      # Create a reconstructed worker exception.
+      #
+      # @param original_class [String]
+      #   Class name of the exception raised inside the worker.
+      # @param original_message [String]
+      #   Message from the exception raised inside the worker.
+      # @param original_backtrace [Array<String>]
+      #   Backtrace captured inside the worker.
+      # @return [void]
       def initialize(original_class:, original_message:, original_backtrace: [])
         @original_class = original_class
         @original_message = original_message
@@ -28,7 +75,14 @@ module CDC
       end
     end
 
-    # Raised when a worker does not return a result before timeout.
+    # Raised when a pool does not receive worker results before the configured
+    # timeout.
+    #
+    # Timeout failures are normally returned inside `CDC::Core::ProcessorResult`
+    # failure objects rather than raised directly to the caller during result
+    # collection.
+    #
+    # @api public
     class TimeoutError < Error; end
   end
 end