cdc-parallel 0.2.2 → 0.2.4

data/sig/cdc/parallel/processor_pool.rbs

@@ -2,60 +2,148 @@ module CDC
   module Parallel
     # Executes one Ractor-safe processor in pre-warmed persistent Ractor workers.
     class ProcessorPool
-      @processor: untyped
-
-      @configuration: untyped
-
-      @workers: untyped
-
+      type work_item = untyped
+      type result = CDC::Core::ProcessorResult
+      type worker_response = result | Hash[Symbol, untyped] | untyped
+      type reply_port = Ractor::Port
+      type worker_inbox = Ractor::Port
+
+      @processor: CDC::Core::Processor
+      @configuration: Configuration
+      @slots: Array[WorkerSlot]
+      @workers: Array[Ractor]
+      @worker_inboxes: Array[worker_inbox]
       @next_worker: Integer
-
-      @shutdown: untyped
+      @dispatch_mutex: Mutex
+      @shutdown: bool
+      @manage_lifecycle: bool
 
       # @param processor [CDC::Core::Processor]
       # @param size [Integer]
-      # @param timeout [Float, nil]
+      # @param timeout [Numeric, nil]
+      # @param supervision [Boolean]
+      # @param max_respawns [Integer]
+      # @param respawn_window [Numeric]
+      # @param respawn_cooldown [Numeric]
+      # @param manage_lifecycle [Boolean]
       # @return [void]
-      def initialize: (processor: untyped, ?size: untyped, ?timeout: untyped?) -> void
+      def initialize: (
+        processor: CDC::Core::Processor,
+        ?size: Integer,
+        ?timeout: Numeric?,
+        ?supervision: bool,
+        ?max_respawns: Integer,
+        ?respawn_window: Numeric,
+        ?respawn_cooldown: Numeric,
+        ?manage_lifecycle: bool
+      ) -> void
+
+      # Total worker-slot respawns since pool boot.
+      #
+      # @return [Integer]
+      def respawns: () -> Integer
+
+      # Whether any worker slot is in crash-loop cooldown.
+      #
+      # @return [Boolean]
+      def degraded?: () -> bool
 
       # Process one work item synchronously.
       #
       # @param item [Object]
       # @return [CDC::Core::ProcessorResult]
-      def process: (untyped item) -> untyped
+      def process: (work_item item) -> result
 
       # 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
+      def process_many: (Array[work_item] items) -> Array[result]
 
-      # Shut down the pool.
+      # Shut down the pool and call processor lifecycle hooks if manage_lifecycle is true.
       #
       # @return [void]
-      def shutdown: () -> untyped
+      def shutdown: () -> void
 
       private
 
-      def signal_workers: () -> untyped
+      def self.start_worker: (CDC::Core::Processor processor, Ractor::Port boot_port) -> Ractor
+
+      def self.run_worker_loop: (untyped safe_processor, untyped inbox) -> nil
+
+      def self.worker_response: (untyped safe_processor, work_item item) -> worker_response
+
+      def dispatch: (Array[work_item] work_items, reply_port reply_port) -> Array[WorkerSlot?]
+
+      def signal_workers: () -> void
+
+      def wait_for_workers: () -> void
+
+      def wait_for_workers_with_timeout: () -> void
+
+      def validate_processor!: (CDC::Core::Processor processor) -> void
+
+      def next_worker_slot: () -> WorkerSlot
+
+      def collect_results: (reply_port reply_port, Integer count, ?Array[WorkerSlot?] assignments) -> Array[result?]
 
-      def wait_for_workers: () -> untyped
+      def collect_results_without_timeout: (reply_port reply_port, Array[result?] results, Array[WorkerSlot?] assignments) -> Array[result?]
 
-      def wait_for_workers_with_timeout: () -> untyped
+      def collect_results_with_timeout: (reply_port reply_port, Array[result?] results, Array[WorkerSlot?] assignments) -> Array[result?]
 
-      def validate_processor!: (untyped processor) -> (nil | untyped)
+      def timeout_results: (Array[result?] results) -> Array[result]
 
-      def build_worker: (untyped processor) -> untyped
+      # One supervised worker position in the pool.
+      class WorkerSlot
+        @index: Integer
+        @processor: CDC::Core::Processor
+        @supervision: bool
+        @max_respawns: Integer
+        @respawn_window: Float
+        @respawn_cooldown: Float
+        @lock: Mutex
+        @worker: Ractor
+        @inbox: Ractor::Port
+        @inflight: Hash[Integer, Ractor::Port]
+        @crashes: Array[Float]
+        @respawns: Integer
+        @shutdown: bool
+        @degraded_until: Float?
+        @supervisor_thread: Thread
 
-      def next_worker: () -> untyped
+        attr_reader respawns: Integer
 
-      def collect_results: (untyped reply_port, Integer count) -> untyped
+        def initialize: (
+          index: Integer,
+          processor: CDC::Core::Processor,
+          supervision: bool,
+          max_respawns: Integer,
+          respawn_window: Numeric,
+          respawn_cooldown: Numeric
+        ) -> void
 
-      def collect_results_without_timeout: (untyped reply_port, untyped results) -> untyped
+        def worker: () -> Ractor
+        def inbox: () -> Ractor::Port
+        def send_work: (Integer index, untyped item, Ractor::Port reply_port) -> void
+        def complete: (Integer index) -> void
+        def degraded?: () -> bool
+        def shutdown: () -> void
+        def join: () -> void
 
-      def collect_results_with_timeout: (untyped reply_port, untyped results) -> untyped
+        private
 
-      def timeout_results: (untyped results) -> untyped
+        def boot!: () -> void
+        def supervise: () -> void
+        def wait_for_worker_death: (Ractor current_worker) -> Exception
+        def fail_inflight: (Exception cause) -> void
+        def send_failure: (Ractor::Port reply_port, Integer index, Exception error) -> void
+        def require_failure: (Exception? failure) -> Exception
+        def send_to_inbox: (untyped inbox, untyped message) -> void
+        def cool_down_if_needed: () -> void
+        def crash_loop?: () -> bool
+        def shutting_down?: () -> bool
+        def degraded_locked?: () -> bool
+      end
     end
   end
 end

data/sig/cdc/parallel/result_collector.rbs

@@ -4,25 +4,27 @@ module CDC
     class ResultCollector
       FAILURE_MARKER: :__cdc_parallel_failure__
 
+      type failure_payload = Hash[Symbol, :__cdc_parallel_failure__ | String | Array[String] | nil]
+
       # Build a shareable success payload that can safely cross a Ractor boundary.
       #
       # @param value [Object]
       # @return [Object]
-      def self.worker_success: (untyped value) -> untyped
+      def self.worker_success: [T] (T value) -> T
 
       # Build a shareable failure payload that can safely cross a Ractor boundary.
       #
       # @param error [Exception]
       # @return [Hash]
-      def self.worker_failure: (untyped error) -> untyped
+      def self.worker_failure: (Exception error) -> failure_payload
 
       # Normalize a worker return value into a ProcessorResult.
       #
       # @param value [Object]
       # @return [CDC::Core::ProcessorResult]
-      def self.normalize: (untyped value) -> untyped
+      def self.normalize: (CDC::Core::ProcessorResult | failure_payload | untyped value) -> CDC::Core::ProcessorResult
 
-      def self.worker_failure?: (untyped value) -> untyped
+      def self.worker_failure?: (untyped value) -> bool
     end
   end
 end

data/sig/cdc/parallel/router.rbs

@@ -2,19 +2,22 @@ module CDC
   module Parallel
     # Routes supported CDC objects to the correct runtime pool.
     class Router
-      @processor_pool: untyped
+      type work_item = CDC::Core::ChangeEvent | CDC::Core::TransactionEnvelope
 
-      @transaction_pool: untyped
+      @processor_pool: ProcessorPool
+
+      @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
 
       # Process a supported CDC work item.
       #
       # @param item [CDC::Core::ChangeEvent, CDC::Core::TransactionEnvelope]
       # @return [CDC::Core::ProcessorResult]
-      def process: (untyped item) -> untyped
+      def process: (work_item item) -> CDC::Core::ProcessorResult
+                 | (untyped item) -> CDC::Core::ProcessorResult
     end
   end
 end

data/sig/cdc/parallel/runtime.rbs

@@ -2,36 +2,67 @@ module CDC
   module Parallel
     # High-level Ractor runtime facade for cdc-core processors.
     class Runtime
-      @processor_pool: untyped
+      type work_item = CDC::Core::ChangeEvent | CDC::Core::TransactionEnvelope
 
-      @transaction_pool: untyped
-
-      @router: untyped
-
-      @shutdown: untyped
+      @processor: CDC::Core::Processor
+      @processor_pool: ProcessorPool
+      @transaction_pool: TransactionPool
+      @router: Router
+      @shutdown: bool
 
       # @param processor [CDC::Core::Processor]
       # @param size [Integer]
-      # @param timeout [Float, nil]
+      # @param timeout [Numeric, nil]
       # @return [void]
-      def initialize: (processor: untyped, ?size: untyped, ?timeout: untyped?) -> void
+      def initialize: (
+        processor: CDC::Core::Processor,
+        ?size: Integer,
+        ?timeout: Numeric?,
+        ?supervision: bool,
+        ?max_respawns: Integer,
+        ?respawn_window: Numeric,
+        ?respawn_cooldown: Numeric
+      ) -> void
 
       # Process a ChangeEvent or TransactionEnvelope.
       #
       # @param item [CDC::Core::ChangeEvent, CDC::Core::TransactionEnvelope]
       # @return [CDC::Core::ProcessorResult]
-      def process: (untyped item) -> untyped
+      def process: (work_item item) -> CDC::Core::ProcessorResult
+                 | (untyped item) -> CDC::Core::ProcessorResult
 
       # Alias for transaction-oriented processing.
       #
       # @param transaction [CDC::Core::TransactionEnvelope]
       # @return [CDC::Core::ProcessorResult]
-      def process_transaction: (untyped transaction) -> untyped
+      def process_transaction: (CDC::Core::TransactionEnvelope transaction) -> CDC::Core::ProcessorResult
 
-      # Shut down all runtime resources.
+      # Shut down all runtime resources and call processor lifecycle hooks.
       #
       # @return [void]
-      def shutdown: () -> (nil | untyped)
+      def shutdown: () -> void
+
+      private
+
+      # Build keyword arguments shared by internal pools.
+      def build_pool_options: (
+        processor: CDC::Core::Processor,
+        size: Integer,
+        timeout: Numeric?,
+        supervision: bool,
+        max_respawns: Integer,
+        respawn_window: Numeric,
+        respawn_cooldown: Numeric
+      ) -> {
+        processor: CDC::Core::Processor,
+        size: Integer,
+        timeout: Numeric?,
+        supervision: bool,
+        max_respawns: Integer,
+        respawn_window: Numeric,
+        respawn_cooldown: Numeric,
+        manage_lifecycle: false
+      }
     end
   end
 end

data/sig/cdc/parallel/transaction_pool.rbs

@@ -2,23 +2,33 @@ module CDC
   module Parallel
     # Processes a TransactionEnvelope as a single ordering-preserving unit.
     class TransactionPool
-      @processor_pool: untyped
+      @processor_pool: ProcessorPool
 
       # @param processor [CDC::Core::Processor]
       # @param size [Integer]
-      # @param timeout [Float, nil]
-      def initialize: (processor: untyped, ?size: untyped, ?timeout: untyped?) -> void
+      # @param timeout [Numeric, nil]
+      # @param manage_lifecycle [Boolean]
+      def initialize: (
+        processor: CDC::Core::Processor,
+        ?size: Integer,
+        ?timeout: Numeric?,
+        ?supervision: bool,
+        ?max_respawns: Integer,
+        ?respawn_window: Numeric,
+        ?respawn_cooldown: Numeric,
+        ?manage_lifecycle: bool
+      ) -> void
 
       # Process all events inside a transaction envelope.
       #
       # @param transaction [CDC::Core::TransactionEnvelope]
       # @return [CDC::Core::ProcessorResult]
-      def process: (untyped transaction) -> untyped
+      def process: (CDC::Core::TransactionEnvelope transaction) -> CDC::Core::ProcessorResult
 
       # Shut down worker resources.
       #
       # @return [void]
-      def shutdown: () -> untyped
+      def shutdown: () -> void
     end
   end
 end

data/sig/cdc/parallel/version.rbs

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cdc-parallel
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.2.4
 platform: ruby
 authors:
 - Ken C. Demanawa
@@ -13,30 +13,16 @@ dependencies:
   name: cdc-core
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0.1'
-- !ruby/object:Gem::Dependency
-  name: ractor-pool
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.4.0
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.4.0
 description: |
   cdc-parallel provides optional Ractor-backed parallel execution for
   cdc-core. It accelerates PostgreSQL Change Data Capture (CDC) event
@@ -70,15 +56,11 @@ files:
 - sig/cdc/parallel/transaction_pool.rbs
 - sig/cdc/parallel/version.rbs
 - sig/cdc_parallel.rbs
-- 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/
+homepage: https://github.com/kanutocd/cdc-parallel
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://kanutocd.github.io/cdc-parallel/
+  homepage_uri: https://github.com/kanutocd/cdc-parallel
   source_code_uri: https://github.com/kanutocd/cdc-parallel
   changelog_uri: https://github.com/kanutocd/cdc-parallel/blob/main/CHANGELOG.md
   documentation_uri: https://kanutocd.github.io/cdc-parallel/

data/sig/shims/cdc_core.rbs

@@ -1,14 +0,0 @@
-module CDC
-  module Core
-    class ProcessorResult
-      def self.success: (untyped event) -> ProcessorResult
-      def self.failure: (untyped error, ?event: untyped) -> ProcessorResult
-    end
-
-    class ChangeEvent
-    end
-
-    class TransactionEnvelope
-    end
-  end
-end

data/sig/shims/etc.rbs

@@ -1,3 +0,0 @@
-module Etc
-  def self.nprocessors: () -> Integer
-end

data/sig/shims/timeout.rbs

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