cdc-concurrent 0.1.0 → 0.1.1

data/lib/cdc/concurrent/router.rb

@@ -2,17 +2,28 @@
 
 module CDC
   module Concurrent
-    # Routes CDC work items to the correct concurrent pool.
+    # Routes CDC work items to the appropriate concurrent execution pool.
+    #
+    # Router is intentionally small. It keeps Runtime focused on lifecycle while
+    # preserving the distinction between individual events, transaction envelopes,
+    # and event batches.
     class Router
-      # @param processor_pool [ProcessorPool]
-      # @param transaction_pool [TransactionPool]
+      # Builds a router using existing processor and transaction pools.
+      #
+      # @param processor_pool [ProcessorPool] Pool used for individual ChangeEvent work and event batches.
+      # @param transaction_pool [TransactionPool] Pool used for TransactionEnvelope work.
+      # @return [void] Does not return a useful value.
       def initialize(processor_pool:, transaction_pool:)
         @processor_pool = processor_pool
         @transaction_pool = transaction_pool
       end
 
-      # @param item [Object]
-      # @return [Object]
+      # Dispatches a supported work item to its matching pool.
+      #
+      # @param item [CDC::Core::ChangeEvent, CDC::Core::TransactionEnvelope and
+      #   Array<CDC::Core::ChangeEvent>] Work item to process.
+      # @raise [UnsupportedWorkItemError] If the item cannot be routed by cdc-concurrent.
+      # @return [CDC::Core::ProcessorResult, Array<CDC::Core::ProcessorResult>] Processing result for the supplied item.
       def process(item)
         case item
         when CDC::Core::ChangeEvent

data/lib/cdc/concurrent/runtime.rb

@@ -3,11 +3,19 @@
 module CDC
   module Concurrent
     # High-level concurrent runtime facade for cdc-core processors.
+    #
+    # Runtime owns the public lifecycle for cdc-concurrent. It wires together the
+    # event processor pool, transaction pool, and router so callers can submit
+    # individual events, batches, or transaction envelopes through one object.
     class Runtime
-      # @param processor [CDC::Core::Processor]
-      # @param concurrency [Integer]
-      # @param timeout [Float, nil]
-      # @param preserve_order [Boolean]
+      # Builds a concurrent runtime for one processor.
+      #
+      # @param processor [CDC::Core::Processor] Processor instance that declares concurrent_safe!.
+      # @param concurrency [Integer] Maximum number of Async tasks allowed to run at once.
+      # @param timeout [Float, nil] Optional per-event processing timeout in seconds.
+      # @param preserve_order [Boolean] Whether batch results should preserve input order.
+      # @raise [UnsafeProcessorError] If the processor does not declare concurrent_safe!.
+      # @return [void] Does not return a useful value.
       def initialize(processor:, concurrency: 100, timeout: nil, preserve_order: true)
         @processor_pool = ProcessorPool.new(processor:, concurrency:, timeout:, preserve_order:)
         @transaction_pool = TransactionPool.new(processor:, concurrency:, timeout:, preserve_order:)
@@ -15,27 +23,39 @@ module CDC
         @shutdown = false
       end
 
-      # @param item [Object]
-      # @return [Object]
+      # Processes a supported work item through the runtime router.
+      #
+      # @param item [CDC::Core::ChangeEvent, CDC::Core::TransactionEnvelope and
+      #         Array<CDC::Core::ChangeEvent>] Work item to process.
+      # @raise [ShutdownError] If the runtime has already been shut down.
+      # @raise [UnsupportedWorkItemError] If the item cannot be routed by cdc-concurrent.
+      # @return [CDC::Core::ProcessorResult, Array<CDC::Core::ProcessorResult>] Processing result for the supplied item.
       def process(item)
         raise ShutdownError, "runtime has been shut down" if @shutdown
 
         @router.process(item)
       end
 
-      # @param events [Array<CDC::Core::ChangeEvent>]
-      # @return [Array<CDC::Core::ProcessorResult>]
+      # Processes a batch of change events.
+      #
+      # @param events [Array<CDC::Core::ChangeEvent>] Events to process through the processor pool.
+      # @return [Array<CDC::Core::ProcessorResult>] Frozen array of normalized processor results.
       def process_many(events)
         process(events)
       end
 
-      # @param transaction [CDC::Core::TransactionEnvelope]
-      # @return [CDC::Core::ProcessorResult]
+      # Processes a transaction envelope as one logical work item.
+      #
+      # @param transaction [CDC::Core::TransactionEnvelope] Transaction whose events should be processed together.
+      # @return [CDC::Core::ProcessorResult] Success result containing event results
+      #         or failure result for the first failed event.
       def process_transaction(transaction)
         process(transaction)
       end
 
-      # @return [void]
+      # Shuts down the runtime and its underlying pools.
+      #
+      # @return [void] Does not return a useful value.
       def shutdown
         return if @shutdown
 

data/lib/cdc/concurrent/transaction_pool.rb

@@ -2,28 +2,46 @@
 
 module CDC
   module Concurrent
-    # Processes TransactionEnvelope events as a single ordering-preserving unit.
+    # Processes TransactionEnvelope events as one logical unit.
+    #
+    # TransactionPool delegates the envelope's events to ProcessorPool while
+    # preserving the envelope-level success/failure contract. Event work may run
+    # concurrently, but the transaction result is returned as a single
+    # CDC::Core::ProcessorResult.
     class TransactionPool
-      # @param processor [CDC::Core::Processor]
-      # @param concurrency [Integer]
-      # @param timeout [Float, nil]
-      # @param preserve_order [Boolean]
+      # Builds a transaction pool backed by an Async processor pool.
+      #
+      # @param processor [CDC::Core::Processor] Processor instance that declares concurrent_safe!.
+      # @param concurrency [Integer] Maximum number of Async tasks allowed to run at once.
+      # @param timeout [Float, nil] Optional per-event processing timeout in seconds.
+      # @param preserve_order [Boolean] Whether event results should preserve transaction event order.
+      # @raise [UnsafeProcessorError] If the processor does not declare concurrent_safe!.
+      # @return [void] Does not return a useful value.
       def initialize(processor:, concurrency: 100, timeout: nil, preserve_order: true)
         @processor_pool = ProcessorPool.new(processor:, concurrency:, timeout:, preserve_order:)
       end
 
-      # @param transaction [CDC::Core::TransactionEnvelope]
-      # @return [CDC::Core::ProcessorResult]
+      # Processes all events inside a transaction envelope.
+      #
+      # @param transaction [CDC::Core::TransactionEnvelope] Transaction envelope whose events should be processed.
+      # @return [CDC::Core::ProcessorResult] Success result containing event results
+      #         or failure result for the first failed event.Z
       def process(transaction)
         results = @processor_pool.process_many(transaction.events).freeze
         failure = results.find(&:failure?)
 
-        return CDC::Core::ProcessorResult.failure(failure.error, event: results) if failure
+        if failure
+          error = failure.error || Error.new("transaction event failed without an error")
+
+          return CDC::Core::ProcessorResult.failure(error, event: results)
+        end
 
         CDC::Core::ProcessorResult.success(results)
       end
 
-      # @return [void]
+      # Shuts down the underlying processor pool.
+      #
+      # @return [void] Does not return a useful value.
       def shutdown
         @processor_pool.shutdown
       end

data/lib/cdc/concurrent/version.rb

@@ -3,6 +3,6 @@
 module CDC
   module Concurrent
     # Current cdc-concurrent version.
-    VERSION = "0.1.0"
+    VERSION = "0.1.1"
   end
 end

data/sig/cdc/concurrent/processor_extensions.rbs

@@ -1,26 +1,39 @@
 module CDC
+  module Core
+    class Processor
+      # Mark this processor class as safe for cdc-concurrent execution.
+      def self.concurrent_safe!: () -> true
+
+      # Whether this processor class declared concurrent safety.
+      def self.concurrent_safe?: () -> bool
+
+      # Whether this processor instance is concurrent-safe.
+      def concurrent_safe?: () -> bool
+    end
+  end
+
   # Optional concurrent runtime adapter for cdc-core processors.
   module Concurrent
     # Adds concurrent-safe declarations to CDC::Core::Processor subclasses.
     module ProcessorExtensions
       # Class methods added to CDC::Core::Processor.
       module ClassMethods
-        @concurrent_safe: untyped
+        @concurrent_safe: bool?
 
         # Declare this processor safe for concurrent execution.
-        def concurrent_safe!: () -> untyped
+        def concurrent_safe!: () -> true
 
         # @return [Boolean] whether instances are concurrent-safe.
-        def concurrent_safe?: () -> untyped
+        def concurrent_safe?: () -> bool
       end
 
       # @return [Boolean] whether this processor instance is concurrent-safe.
-      def concurrent_safe?: () -> untyped
+      def concurrent_safe?: () -> bool
     end
 
     # Installs concurrent-safe declarations on CDC::Core::Processor.
     #
     # @return [void]
-    def self.install_processor_extensions!: () -> untyped
+    def self.install_processor_extensions!: () -> void
   end
 end

data/sig/cdc/concurrent/processor_pool.rbs

@@ -2,42 +2,42 @@ module CDC
   module Concurrent
     # Executes one concurrent-safe processor using Async tasks.
     class ProcessorPool
-      @processor: untyped
+      @processor: processor
 
-      @configuration: untyped
+      @configuration: Configuration
 
-      @shutdown: untyped
+      @shutdown: bool
 
       # @param processor [CDC::Core::Processor]
       # @param concurrency [Integer]
       # @param timeout [Float, nil]
       # @param preserve_order [Boolean]
-      def initialize: (processor: untyped, ?concurrency: ::Integer, ?timeout: untyped?, ?preserve_order: bool) -> void
+      def initialize: (processor: processor, ?concurrency: ::Integer, ?timeout: ::Float?, ?preserve_order: bool) -> void
 
       # @param event [CDC::Core::ChangeEvent]
       # @return [CDC::Core::ProcessorResult]
-      def process: (untyped event) -> untyped
+      def process: (change_event event) -> processor_result
 
       # @param events [Array<CDC::Core::ChangeEvent>]
       # @return [Array<CDC::Core::ProcessorResult>]
-      def process_many: (untyped events) -> (::Array[untyped] | untyped)
+      def process_many: (::Array[change_event] events) -> processor_results
 
       # @return [void]
-      def shutdown: () -> untyped
+      def shutdown: () -> void
 
       private
 
-      def validate_processor!: (untyped processor) -> (nil | untyped)
+      def validate_processor!: (processor processor) -> nil
 
-      def empty_results: () -> ::Array[untyped]
+      def empty_results: () -> processor_results
 
-      def process_batch: (untyped events, untyped indexed_results) -> untyped
+      def process_batch: (::Array[change_event] events, ::Array[[::Integer, processor_result]] indexed_results) -> untyped
 
-      def process_one: (untyped event) -> untyped
+      def process_one: (change_event event) -> untyped
 
-      def process_with_task: (untyped task, untyped event) -> untyped
+      def process_with_task: (untyped task, change_event event) -> processor_result
 
-      def call_processor: (untyped task, untyped event) -> untyped
+      def call_processor: (untyped task, change_event event) -> untyped
     end
   end
 end

data/sig/cdc/concurrent/result_collector.rbs

@@ -4,11 +4,11 @@ module CDC
     class ResultCollector
       # @param value [Object]
       # @return [CDC::Core::ProcessorResult]
-      def self.normalize: (untyped value) -> untyped
+      def self.normalize: (untyped value) -> processor_result
 
       # @param error [Exception]
       # @return [CDC::Core::ProcessorResult]
-      def self.failure: (untyped error) -> untyped
+      def self.failure: (::Exception error) -> processor_result
     end
   end
 end

data/sig/cdc/concurrent/router.rbs

@@ -2,17 +2,20 @@ module CDC
   module Concurrent
     # Routes CDC work items to the correct concurrent pool.
     class Router
-      @processor_pool: untyped
+      @processor_pool: ProcessorPool
 
-      @transaction_pool: untyped
+      @transaction_pool: TransactionPool
 
       # @param processor_pool [ProcessorPool]
       # @param transaction_pool [TransactionPool]
-      def initialize: (processor_pool: untyped, transaction_pool: untyped) -> void
+      def initialize: (processor_pool: ProcessorPool, transaction_pool: TransactionPool) -> void
 
       # @param item [Object]
       # @return [Object]
-      def process: (untyped item) -> untyped
+      def process: (change_event item) -> processor_result
+                 | (transaction_envelope item) -> processor_result
+                 | (::Array[change_event] item) -> processor_results
+                 | (work_item item) -> work_result
     end
   end
 end

data/sig/cdc/concurrent/runtime.rbs

@@ -2,34 +2,36 @@ module CDC
   module Concurrent
     # High-level concurrent runtime facade for cdc-core processors.
     class Runtime
-      @processor_pool: untyped
+      @processor_pool: ProcessorPool
 
-      @transaction_pool: untyped
+      @transaction_pool: TransactionPool
 
-      @router: untyped
+      @router: Router
 
-      @shutdown: untyped
+      @shutdown: bool
 
       # @param processor [CDC::Core::Processor]
       # @param concurrency [Integer]
       # @param timeout [Float, nil]
       # @param preserve_order [Boolean]
-      def initialize: (processor: untyped, ?concurrency: ::Integer, ?timeout: untyped?, ?preserve_order: bool) -> void
+      def initialize: (processor: processor, ?concurrency: ::Integer, ?timeout: ::Float?, ?preserve_order: bool) -> void
 
       # @param item [Object]
       # @return [Object]
-      def process: (untyped item) -> untyped
+      def process: (change_event item) -> processor_result
+                 | (transaction_envelope item) -> processor_result
+                 | (::Array[change_event] item) -> processor_results
 
       # @param events [Array<CDC::Core::ChangeEvent>]
       # @return [Array<CDC::Core::ProcessorResult>]
-      def process_many: (untyped events) -> untyped
+      def process_many: (::Array[change_event] events) -> processor_results
 
       # @param transaction [CDC::Core::TransactionEnvelope]
       # @return [CDC::Core::ProcessorResult]
-      def process_transaction: (untyped transaction) -> untyped
+      def process_transaction: (transaction_envelope transaction) -> processor_result
 
       # @return [void]
-      def shutdown: () -> (nil | untyped)
+      def shutdown: () -> void
     end
   end
 end

data/sig/cdc/concurrent/transaction_pool.rbs

@@ -2,20 +2,20 @@ module CDC
   module Concurrent
     # Processes TransactionEnvelope events as a single ordering-preserving unit.
     class TransactionPool
-      @processor_pool: untyped
+      @processor_pool: ProcessorPool
 
       # @param processor [CDC::Core::Processor]
       # @param concurrency [Integer]
       # @param timeout [Float, nil]
       # @param preserve_order [Boolean]
-      def initialize: (processor: untyped, ?concurrency: ::Integer, ?timeout: untyped?, ?preserve_order: bool) -> void
+      def initialize: (processor: processor, ?concurrency: ::Integer, ?timeout: ::Float?, ?preserve_order: bool) -> void
 
       # @param transaction [CDC::Core::TransactionEnvelope]
       # @return [CDC::Core::ProcessorResult]
-      def process: (untyped transaction) -> untyped
+      def process: (transaction_envelope transaction) -> processor_result
 
       # @return [void]
-      def shutdown: () -> untyped
+      def shutdown: () -> void
     end
   end
 end

data/sig/cdc/concurrent/version.rbs

@@ -1,6 +1,6 @@
 module CDC
   module Concurrent
     # Current cdc-concurrent version.
-    VERSION: "0.1.0"
+    VERSION: "0.1.1"
   end
 end

data/sig/cdc/concurrent.rbs

@@ -1,5 +1,12 @@
 module CDC
   # Optional concurrent runtime adapter for cdc-core processors.
   module Concurrent
+    type change_event = ::CDC::Core::ChangeEvent
+    type processor = ::CDC::Core::Processor
+    type processor_result = ::CDC::Core::ProcessorResult
+    type processor_results = ::Array[processor_result]
+    type transaction_envelope = ::CDC::Core::TransactionEnvelope
+    type work_item = change_event | transaction_envelope | ::Array[change_event]
+    type work_result = processor_result | processor_results
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cdc-concurrent
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Ken C. Demanawa
@@ -30,6 +30,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.3
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -37,6 +40,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.3
 description: |
   cdc-concurrent provides optional Async-backed I/O-concurrent execution for
   cdc-core. It accelerates I/O-bound PostgreSQL Change Data Capture (CDC)
@@ -50,6 +56,8 @@ files:
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
+- benchmark/README.md
+- benchmark/processor_pool_benchmark.rb
 - lib/cdc/concurrent.rb
 - lib/cdc/concurrent/configuration.rb
 - lib/cdc/concurrent/errors.rb
@@ -72,8 +80,6 @@ files:
 - sig/cdc/concurrent/transaction_pool.rbs
 - sig/cdc/concurrent/version.rbs
 - sig/cdc_concurrent.rbs
-- sig/shims/async.rbs
-- sig/shims/cdc_core.rbs
 homepage: https://kanutocd.github.io/cdc-concurrent
 licenses:
 - MIT

data/sig/shims/async.rbs

@@ -1,20 +0,0 @@
-module Kernel
-  private
-
-  def Async: () { (Async::Task) -> untyped } -> Async::Task
-end
-
-module Async
-  class Task
-    def with_timeout: (untyped timeout) { () -> untyped } -> untyped
-    def wait: () -> untyped
-  end
-
-  class Semaphore
-    def initialize: (Integer limit, parent: Task) -> void
-    def async: () { (Task) -> untyped } -> Task
-  end
-
-  class TimeoutError < StandardError
-  end
-end

data/sig/shims/cdc_core.rbs

@@ -1,31 +0,0 @@
-module CDC
-  module Core
-    class Processor
-      def self.extend: (Module mod) -> self
-      def self.include: (Module mod) -> self
-
-      def process: (untyped event) -> untyped
-    end
-
-    class ProcessorResult
-      attr_reader status: Symbol
-      attr_reader event: untyped
-      attr_reader error: untyped
-      attr_reader metadata: untyped
-
-      def self.success: (?untyped event, ?metadata: untyped) -> ProcessorResult
-      def self.failure: (untyped error, ?event: untyped, ?metadata: untyped) -> ProcessorResult
-
-      def success?: () -> bool
-      def failure?: () -> bool
-      def skipped?: () -> bool
-    end
-
-    class ChangeEvent
-    end
-
-    class TransactionEnvelope
-      attr_reader events: Array[ChangeEvent]
-    end
-  end
-end