ractor-pool 0.2.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 73bb38fa65f10e0a6eb11265acef8a298e6d0109a2c5b2c1dba750b38a0d5ed4
-  data.tar.gz: 4fa41532f78bceea5ddcd33a4c9ce9f9efefe114edb37de5953cd97438f349ad
+  metadata.gz: 13aa15dab296025cc8fa8348a4477bd8afd2db09b24ea4e13c43a17cca976cd2
+  data.tar.gz: b99432e86a0e93b69aa84867b869a0502469b402a297698599175442987cc23f
 SHA512:
-  metadata.gz: fee7cb83e33e99e265484986b1208c0742216322cd7bc0f23a3de14f38f9fe71d21adbccec1179f51cd4aa4f0875c8291ae2b621a0599edbb479357bc2dabe2c
-  data.tar.gz: 8135a1c1fbc84d70e0b6650d87715a94ee2322a67e6471786df29f8c2c0cd927a4de061301982a1802ad4a5b2f408e8aa34f1ae31679b9a5edbc4e1cfb5481cc
+  metadata.gz: 8f85b3c281484b9daf22e6e0fe2c195ca4a5a67640e3913d70f93cd109c022e3138cbae924477de09e2400c552b9b4c19eb386cf9b5b3479ec6bf60e382cbb4d
+  data.tar.gz: 6101a788de91cbe8f681cfa3c3c05556154061f0f96910e2474c1b083b5c283455d2ee1c525d30f8e73785148ad6392dbf1464f578cdb8b07670718b911bfba5

data/.buildkite/pipeline.yml

@@ -6,6 +6,7 @@ steps:
       - bundle exec rake
 
   - label: ":ruby: Ruby head"
+    soft_fail: true
     image: "rubylang/ruby:master-dev"
     commands:
       - apt-get update && apt-get install -y libyaml-dev

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 ## [Unreleased]
 
+## [0.3.1] - 2026-05-12
+
+- Fix `result_port` race condition in single-worker shutdown
+
+## [0.3.0] - 2026-05-08
+
+- Replace state atom with separate `@in_flight` and `@shutdown` atoms
+- Add `on_error:` worker error callback
+- Update `Ractor` warning suppression regex
+
 ## [0.2.0] - 2026-01-07
 
 - Require Ruby >= 4.0.0

data/lib/ractor-pool/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class RactorPool
-  VERSION = "0.2.0"
+  VERSION = "0.3.1"
 end

data/lib/ractor-pool.rb

@@ -4,7 +4,7 @@
 require "warning"
 require "atomic-ruby/atom"
 
-Warning.ignore(/Ractor is experimental/, __FILE__)
+Warning.ignore(/Ractor API is experimental/, __FILE__)
 
 # A thread-safe, lock-free pool of Ractor workers with a coordinator pattern for distributing work.
 #
@@ -35,7 +35,7 @@ Warning.ignore(/Ractor is experimental/, __FILE__)
 #
 #   p counter.value #=> 10
 #
-# @see https://docs.ruby-lang.org/en/master/ractor_md.html Ractor Guide
+# @see https://docs.ruby-lang.org/en/master/language/ractor_md.html Ractor Guide
 # @see https://docs.ruby-lang.org/en/master/Ractor.html Ractor API
 # @see https://docs.ruby-lang.org/en/master/Ractor/Port.html Ractor::Port API
 # @see https://github.com/joshuay03/atomic-ruby atomic-ruby gem
@@ -54,22 +54,28 @@ class RactorPool
   # @rbs @size: Integer
   # @rbs @worker: ^(untyped) -> untyped
   # @rbs @name: String?
+  # @rbs @on_error: (^(Exception) -> void | nil)
   # @rbs @result_handler: (^(untyped) -> void | nil)
-  # @rbs @state: Atom[Hash[Symbol, bool | Integer]]
+  # @rbs @in_flight: Atom[Integer]
+  # @rbs @shutdown: Atom[bool]
   # @rbs @result_port: Ractor::Port?
+  # @rbs @error_port: Ractor::Port?
   # @rbs @coordinator: Ractor?
   # @rbs @workers: Array[Ractor]
   # @rbs @collector: Thread?
+  # @rbs @error_collector: Thread?
 
   # Creates a new RactorPool with the specified number of workers.
   #
   # @param size [Integer] number of worker ractors to create
   # @param worker [Proc] a shareable proc that processes each work item
   # @param name [String, nil] optional name for the pool, used in thread/ractor names
+  # @param on_error [Proc, nil] optional shareable proc called with the raised exception when a worker raises
   # @yieldparam result [Object] the result returned by the worker proc
   # @return [void]
   # @raise [ArgumentError] if size is not a positive integer
   # @raise [ArgumentError] if worker is not a proc
+  # @raise [ArgumentError] if on_error is given but is not a proc
   #
   # @example With result handler
   #   pool = RactorPool.new(size: 4, worker: proc { it }) { |result| puts result }
@@ -77,22 +83,32 @@ class RactorPool
   # @example Without result handler
   #   pool = RactorPool.new(size: 4, worker: proc { it })
   #
-  # @rbs (?size: Integer, worker: ^(untyped) -> untyped, ?name: String?) ?{ (untyped) -> void } -> void
-  def initialize(size: Etc.nprocessors, worker:, name: nil, &result_handler)
+  # @example With error handler
+  #   error_count = Atom.new(0)
+  #   on_error = proc { error_count.swap { |count| count + 1 } }
+  #   pool = RactorPool.new(size: 4, worker: proc { raise }, on_error: on_error)
+  #
+  # @rbs (?size: Integer, worker: ^(untyped) -> untyped, ?name: String?, ?on_error: (^(Exception) -> void | nil)) ?{ (untyped) -> void } -> void
+  def initialize(size: Etc.nprocessors, worker:, name: nil, on_error: nil, &result_handler)
     raise ArgumentError, "size must be a positive Integer" unless size.is_a?(Integer) && size > 0
     raise ArgumentError, "worker must be a Proc" unless worker.is_a?(Proc)
+    raise ArgumentError, "on_error must be a Proc" if on_error && !on_error.is_a?(Proc)
 
     @size = size
     @worker = Ractor.shareable_proc(&worker)
     @name = name
+    @on_error = Ractor.shareable_proc(&on_error) if on_error
     @result_handler = result_handler
 
-    @state = Atom.new(in_flight: 0, shutdown: false)
+    @in_flight = Atom.new(0)
+    @shutdown  = Atom.new(false)
 
     @result_port = Ractor::Port.new if result_handler
+    @error_port  = Ractor::Port.new unless on_error
     @coordinator = start_coordinator if size > 1
     @workers = start_workers
     @collector = start_collector
+    @error_collector = start_error_collector
   end
 
   # Queues a work item to be processed by an available worker.
@@ -107,21 +123,19 @@ class RactorPool
   #
   # @rbs (untyped work) -> void
   def <<(work)
-    state = @state.swap do |current_state|
-      if current_state[:shutdown]
-        current_state
-      else
-        current_state.merge(in_flight: current_state[:in_flight] + 1)
-      end
+    raise EnqueuedWorkAfterShutdownError if @shutdown.value
+
+    @in_flight.swap { |count| count + 1 }
+
+    if @shutdown.value
+      @in_flight.swap { |count| count - 1 }
+      raise EnqueuedWorkAfterShutdownError
     end
-    raise EnqueuedWorkAfterShutdownError if state[:shutdown]
 
     begin
       (@coordinator || @workers.first).send(work, move: true)
     ensure
-      @state.swap do |current_state|
-        current_state.merge(in_flight: current_state[:in_flight] - 1)
-      end
+      @in_flight.swap { |count| count - 1 }
     end
   end
 
@@ -132,7 +146,7 @@ class RactorPool
   # 2. Waits for all in-flight work submissions to complete
   # 3. Allows all queued work to complete
   # 4. Waits for all workers to finish
-  # 5. Waits for all results to be processed
+  # 5. Waits for all results and errors to be processed
   #
   # This method is idempotent and can be called multiple times safely.
   #
@@ -144,22 +158,29 @@ class RactorPool
   # @rbs () -> void
   def shutdown
     already_shutdown = false
-    @state.swap do |current_state|
-      if current_state[:shutdown]
+    @shutdown.swap do |current|
+      if current
         already_shutdown = true
-        current_state
+        current
       else
-        current_state.merge(shutdown: true)
+        true
       end
     end
     return if already_shutdown
 
-    Thread.pass until @state.value[:in_flight] == 0
+    Thread.pass until @in_flight.value.zero?
 
-    @coordinator&.send(SHUTDOWN, move: true) ||
-      (@workers.first.send(SHUTDOWN, move: true) && @result_port&.send(SHUTDOWN, move: true))
-    @workers.each(&:join)
-    @coordinator&.join
+    if @coordinator
+      @coordinator.send(SHUTDOWN, move: true)
+      @workers.each(&:join)
+      @coordinator.join
+    else
+      @workers.first.send(SHUTDOWN, move: true)
+      @workers.each(&:join)
+      @result_port&.send(SHUTDOWN, move: true)
+    end
+    @error_port&.send(SHUTDOWN, move: true)
+    @error_collector&.join
     @collector&.join
   end
 
@@ -225,7 +246,7 @@ class RactorPool
       ractor_name = String.new("#{self.class.name} ractor #{index}")
       ractor_name << " for #{@name}" if @name
 
-      Ractor.new(@worker, @coordinator, @result_port, name: ractor_name) do |worker, coordinator, result_port|
+      Ractor.new(@worker, @on_error, @error_port, @coordinator, @result_port, name: ractor_name) do |worker, on_error, error_port, coordinator, result_port|
         loop do
           coordinator&.send(Ractor.current, move: true)
 
@@ -237,9 +258,7 @@ class RactorPool
 
             result_port&.send(result, move: true)
           rescue => error
-            puts "#{Ractor.current.name} rescued:"
-            puts "#{error.class}: #{error.message}"
-            puts error.backtrace.join("\n")
+            on_error ? on_error.call(error) : error_port.send(error.full_message, move: true)
           end
         end
       end
@@ -264,4 +283,23 @@ class RactorPool
       end
     end
   end
+
+  # @rbs () -> Thread?
+  def start_error_collector
+    return if @on_error
+
+    thread_name = String.new("#{self.class.name} error collector thread")
+    thread_name << " for #{@name}" if @name
+
+    Thread.new(@error_port, thread_name) do |error_port, name|
+      Thread.current.name = name
+
+      loop do
+        message = error_port.receive
+        break if message == SHUTDOWN
+
+        warn message
+      end
+    end
+  end
 end

data/sig/generated/ractor-pool.rbs

@@ -29,7 +29,7 @@
 #
 #   p counter.value #=> 10
 #
-# @see https://docs.ruby-lang.org/en/master/ractor_md.html Ractor Guide
+# @see https://docs.ruby-lang.org/en/master/language/ractor_md.html Ractor Guide
 # @see https://docs.ruby-lang.org/en/master/Ractor.html Ractor API
 # @see https://docs.ruby-lang.org/en/master/Ractor/Port.html Ractor::Port API
 # @see https://github.com/joshuay03/atomic-ruby atomic-ruby gem
@@ -44,18 +44,26 @@ class RactorPool
 
   SHUTDOWN: ::Symbol
 
+  @error_collector: Thread?
+
   @collector: Thread?
 
   @workers: Array[Ractor]
 
   @coordinator: Ractor?
 
+  @error_port: Ractor::Port?
+
   @result_port: Ractor::Port?
 
-  @state: Atom[Hash[Symbol, bool | Integer]]
+  @shutdown: Atom[bool]
+
+  @in_flight: Atom[Integer]
 
   @result_handler: ^(untyped) -> void | nil
 
+  @on_error: ^(Exception) -> void | nil
+
   @name: String?
 
   @worker: ^(untyped) -> untyped
@@ -67,10 +75,12 @@ class RactorPool
   # @param size [Integer] number of worker ractors to create
   # @param worker [Proc] a shareable proc that processes each work item
   # @param name [String, nil] optional name for the pool, used in thread/ractor names
+  # @param on_error [Proc, nil] optional shareable proc called with the raised exception when a worker raises
   # @yieldparam result [Object] the result returned by the worker proc
   # @return [void]
   # @raise [ArgumentError] if size is not a positive integer
   # @raise [ArgumentError] if worker is not a proc
+  # @raise [ArgumentError] if on_error is given but is not a proc
   #
   # @example With result handler
   #   pool = RactorPool.new(size: 4, worker: proc { it }) { |result| puts result }
@@ -78,8 +88,13 @@ class RactorPool
   # @example Without result handler
   #   pool = RactorPool.new(size: 4, worker: proc { it })
   #
-  # @rbs (?size: Integer, worker: ^(untyped) -> untyped, ?name: String?) ?{ (untyped) -> void } -> void
-  def initialize: (worker: ^(untyped) -> untyped, ?size: Integer, ?name: String?) ?{ (untyped) -> void } -> void
+  # @example With error handler
+  #   error_count = Atom.new(0)
+  #   on_error = proc { error_count.swap { |count| count + 1 } }
+  #   pool = RactorPool.new(size: 4, worker: proc { raise }, on_error: on_error)
+  #
+  # @rbs (?size: Integer, worker: ^(untyped) -> untyped, ?name: String?, ?on_error: (^(Exception) -> void | nil)) ?{ (untyped) -> void } -> void
+  def initialize: (worker: ^(untyped) -> untyped, ?size: Integer, ?name: String?, ?on_error: ^(Exception) -> void | nil) ?{ (untyped) -> void } -> void
 
   # Queues a work item to be processed by an available worker.
   #
@@ -101,7 +116,7 @@ class RactorPool
   # 2. Waits for all in-flight work submissions to complete
   # 3. Allows all queued work to complete
   # 4. Waits for all workers to finish
-  # 5. Waits for all results to be processed
+  # 5. Waits for all results and errors to be processed
   #
   # This method is idempotent and can be called multiple times safely.
   #
@@ -123,4 +138,7 @@ class RactorPool
 
   # @rbs () -> Thread?
   def start_collector: () -> Thread?
+
+  # @rbs () -> Thread?
+  def start_error_collector: () -> Thread?
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ractor-pool
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Joshua Young
@@ -73,7 +73,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.10
 specification_version: 4
 summary: A thread-safe, lock-free pool of Ractor workers with a coordinator pattern
   for distributing work