ractor-pool 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 73bb38fa65f10e0a6eb11265acef8a298e6d0109a2c5b2c1dba750b38a0d5ed4
-  data.tar.gz: 4fa41532f78bceea5ddcd33a4c9ce9f9efefe114edb37de5953cd97438f349ad
+  metadata.gz: b97336e3bda02791d66cbef83761b58ff599afca2e58698bd79e7aa5bdedc497
+  data.tar.gz: 77b0ff65e53978436edc7701c204415709092f96a71f1c834e7ce719c75fc3d4
 SHA512:
-  metadata.gz: fee7cb83e33e99e265484986b1208c0742216322cd7bc0f23a3de14f38f9fe71d21adbccec1179f51cd4aa4f0875c8291ae2b621a0599edbb479357bc2dabe2c
-  data.tar.gz: 8135a1c1fbc84d70e0b6650d87715a94ee2322a67e6471786df29f8c2c0cd927a4de061301982a1802ad4a5b2f408e8aa34f1ae31679b9a5edbc4e1cfb5481cc
+  metadata.gz: acdd99e1c5c20f0d628353abe9682a9283c1d60d5b5f1247d366c08e91db3dc19e62797a8d3347fd49c8498e1896e57711637a0cea3c05359f4aa300f3f73eee
+  data.tar.gz: 5cf2b4e221ec273c5ed038c256d36e4b29f58619eee6d7412e68d498288e593373a874118b6b4f58e83c8a20009c800e3000d5aa31dc88cc7b6fc5ed277c33ed

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 ## [Unreleased]
 
+## [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.0"
 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.
 #
@@ -54,11 +54,15 @@ 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 @error_collector: Thread?
   # @rbs @collector: Thread?
 
   # Creates a new RactorPool with the specified number of workers.
@@ -66,10 +70,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 }
@@ -77,21 +83,31 @@ 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
+    @error_collector = start_error_collector
     @collector = start_collector
   end
 
@@ -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,24 @@ 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
+    @error_port&.send(SHUTDOWN, move: true)
+    @error_collector&.join
     @collector&.join
   end
 
@@ -225,7 +241,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,15 +253,32 @@ 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
     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
+
   # @rbs () -> Thread?
   def start_collector
     return unless @result_handler

data/sig/generated/ractor-pool.rbs

@@ -46,16 +46,24 @@ class RactorPool
 
   @collector: Thread?
 
+  @error_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.
   #
@@ -121,6 +136,9 @@ class RactorPool
   # @rbs () -> Array[Ractor]
   def start_workers: () -> Array[Ractor]
 
+  # @rbs () -> Thread?
+  def start_error_collector: () -> Thread?
+
   # @rbs () -> Thread?
   def start_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.0
 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.6
 specification_version: 4
 summary: A thread-safe, lock-free pool of Ractor workers with a coordinator pattern
   for distributing work