ractor-pool 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b97336e3bda02791d66cbef83761b58ff599afca2e58698bd79e7aa5bdedc497
-  data.tar.gz: 77b0ff65e53978436edc7701c204415709092f96a71f1c834e7ce719c75fc3d4
+  metadata.gz: 2d8741738f0de76db49cbbbaccc701b687af3df13ce9802205c7661a10519126
+  data.tar.gz: 337ce4d26b7735ec2517c2b88e76f2b11bef87124e3581a74772e68fbd3b6e57
 SHA512:
-  metadata.gz: acdd99e1c5c20f0d628353abe9682a9283c1d60d5b5f1247d366c08e91db3dc19e62797a8d3347fd49c8498e1896e57711637a0cea3c05359f4aa300f3f73eee
-  data.tar.gz: 5cf2b4e221ec273c5ed038c256d36e4b29f58619eee6d7412e68d498288e593373a874118b6b4f58e83c8a20009c800e3000d5aa31dc88cc7b6fc5ed277c33ed
+  metadata.gz: 663d3b28aeab7e0341bbfd5d78540c670fbb74e3cfc89679572093067fc72396028d3b1637c224676d4c52d86aaafd688143e28499217f0b513c7d5035ba42c4
+  data.tar.gz: 6a9fc3ec933ece355f9bba48ac1de2980a3c105f0baaf2a13684ab74a54028daec5f2695dee25c4d970d3dc71f7bd066d207977424f8f199c44f8f61e9e6ae85

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,13 @@
 ## [Unreleased]
 
+## [0.4.0] - 2026-05-20
+
+- Add `:round_robin` dispatch strategy
+
+## [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

data/README.md

@@ -3,7 +3,7 @@
 ![Version](https://img.shields.io/gem/v/ractor-pool)
 ![Build](https://badge.buildkite.com/f5f08eba1c869dee6e9e87dd66b241059d8fbefaaed6c56d86.svg)
 
-A thread-safe, lock-free pool of Ractor workers with a coordinator pattern for distributing work.
+A thread-safe, lock-free pool of Ractor workers with coordinator or round-robin dispatch for distributing work.
 
 ## Installation
 

data/lib/ractor-pool/version.rb

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

data/lib/ractor-pool.rb

@@ -6,11 +6,16 @@ require "atomic-ruby/atom"
 
 Warning.ignore(/Ractor API is experimental/, __FILE__)
 
-# A thread-safe, lock-free pool of Ractor workers with a coordinator pattern for distributing work.
+# A thread-safe, lock-free pool of Ractor workers with coordinator or round-robin dispatch for distributing work.
 #
 # RactorPool manages a fixed number of worker ractors that process work items in parallel.
-# Work is distributed on-demand to idle workers, ensuring efficient utilisation. Results
-# are collected and passed to a result handler running in a separate thread.
+# The +:coordinator+ strategy (the default) routes each work item to whichever worker is
+# currently idle via a dedicated coordinator Ractor, so a slow item on one worker does not
+# block faster items from being picked up by other workers. Use it when work items have
+# variable cost. The +:round_robin+ strategy dispatches work to workers in turn, so a slow
+# item on one worker queues the next item destined for that worker behind it, even if other
+# workers are idle. Use it when work items have uniform cost. Results are collected and
+# passed to a result handler running in a separate thread.
 #
 # @example Basic usage
 #   results = []
@@ -35,7 +40,7 @@ Warning.ignore(/Ractor API 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
@@ -48,33 +53,40 @@ class RactorPool
     def message = "cannot queue work after shutdown"
   end
 
+  STRATEGIES = %i[coordinator round_robin].freeze
+  private_constant :STRATEGIES
+
   SHUTDOWN = :shutdown
   private_constant :SHUTDOWN
 
   # @rbs @size: Integer
   # @rbs @worker: ^(untyped) -> untyped
+  # @rbs @strategy: Symbol
   # @rbs @name: String?
   # @rbs @on_error: (^(Exception) -> void | nil)
   # @rbs @result_handler: (^(untyped) -> void | nil)
   # @rbs @in_flight: Atom[Integer]
   # @rbs @shutdown: Atom[bool]
+  # @rbs @next_worker_index: Atom[Integer]?
   # @rbs @result_port: Ractor::Port?
   # @rbs @error_port: Ractor::Port?
   # @rbs @coordinator: Ractor?
   # @rbs @workers: Array[Ractor]
-  # @rbs @error_collector: Thread?
   # @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 strategy [Symbol] dispatch strategy, either +:coordinator+ (the default) or +:round_robin+
   # @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 strategy is not +:coordinator+ or +:round_robin+
   # @raise [ArgumentError] if on_error is given but is not a proc
   #
   # @example With result handler
@@ -83,32 +95,38 @@ class RactorPool
   # @example Without result handler
   #   pool = RactorPool.new(size: 4, worker: proc { it })
   #
+  # @example With round-robin strategy
+  #   pool = RactorPool.new(size: 4, strategy: :round_robin, worker: proc { it })
+  #
   # @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)
+  # @rbs (?size: Integer, worker: ^(untyped) -> untyped, ?strategy: Symbol, ?name: String?, ?on_error: (^(Exception) -> void | nil)) ?{ (untyped) -> void } -> void
+  def initialize(size: Etc.nprocessors, worker:, strategy: :coordinator, 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, "strategy must be one of #{STRATEGIES.inspect}" unless STRATEGIES.include?(strategy)
     raise ArgumentError, "on_error must be a Proc" if on_error && !on_error.is_a?(Proc)
 
     @size = size
     @worker = Ractor.shareable_proc(&worker)
+    @strategy = strategy
     @name = name
     @on_error = Ractor.shareable_proc(&on_error) if on_error
     @result_handler = result_handler
 
     @in_flight = Atom.new(0)
     @shutdown  = Atom.new(false)
+    @next_worker_index = Atom.new(-1) if size > 1 && strategy == :round_robin
 
     @result_port = Ractor::Port.new if result_handler
     @error_port  = Ractor::Port.new unless on_error
-    @coordinator = start_coordinator if size > 1
+    @coordinator = start_coordinator if size > 1 && strategy == :coordinator
     @workers = start_workers
-    @error_collector = start_error_collector
     @collector = start_collector
+    @error_collector = start_error_collector
   end
 
   # Queues a work item to be processed by an available worker.
@@ -132,8 +150,16 @@ class RactorPool
       raise EnqueuedWorkAfterShutdownError
     end
 
+    target = if @coordinator
+               @coordinator
+             elsif @next_worker_index
+               @workers[@next_worker_index.swap { |index| (index + 1) % @size }]
+             else
+               @workers.first
+             end
+
     begin
-      (@coordinator || @workers.first).send(work, move: true)
+      target.send(work, move: true)
     ensure
       @in_flight.swap { |count| count - 1 }
     end
@@ -170,10 +196,15 @@ class RactorPool
 
     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.each { |worker| worker.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
@@ -261,39 +292,39 @@ class RactorPool
   end
 
   # @rbs () -> Thread?
-  def start_error_collector
-    return if @on_error
+  def start_collector
+    return unless @result_handler
 
-    thread_name = String.new("#{self.class.name} error collector thread")
+    thread_name = String.new("#{self.class.name} collector thread")
     thread_name << " for #{@name}" if @name
 
-    Thread.new(@error_port, thread_name) do |error_port, name|
+    Thread.new(@result_port, @result_handler, thread_name) do |result_port, result_handler, name|
       Thread.current.name = name
 
       loop do
-        message = error_port.receive
-        break if message == SHUTDOWN
+        result = result_port.receive
+        break if result == SHUTDOWN
 
-        warn message
+        result_handler.call(result)
       end
     end
   end
 
   # @rbs () -> Thread?
-  def start_collector
-    return unless @result_handler
+  def start_error_collector
+    return if @on_error
 
-    thread_name = String.new("#{self.class.name} collector thread")
+    thread_name = String.new("#{self.class.name} error collector thread")
     thread_name << " for #{@name}" if @name
 
-    Thread.new(@result_port, @result_handler, thread_name) do |result_port, result_handler, name|
+    Thread.new(@error_port, thread_name) do |error_port, name|
       Thread.current.name = name
 
       loop do
-        result = result_port.receive
-        break if result == SHUTDOWN
+        message = error_port.receive
+        break if message == SHUTDOWN
 
-        result_handler.call(result)
+        warn message
       end
     end
   end

data/sig/generated/ractor-pool.rbs

@@ -1,10 +1,15 @@
 # Generated from lib/ractor-pool.rb with RBS::Inline
 
-# A thread-safe, lock-free pool of Ractor workers with a coordinator pattern for distributing work.
+# A thread-safe, lock-free pool of Ractor workers with coordinator or round-robin dispatch for distributing work.
 #
 # RactorPool manages a fixed number of worker ractors that process work items in parallel.
-# Work is distributed on-demand to idle workers, ensuring efficient utilisation. Results
-# are collected and passed to a result handler running in a separate thread.
+# The +:coordinator+ strategy (the default) routes each work item to whichever worker is
+# currently idle via a dedicated coordinator Ractor, so a slow item on one worker does not
+# block faster items from being picked up by other workers. Use it when work items have
+# variable cost. The +:round_robin+ strategy dispatches work to workers in turn, so a slow
+# item on one worker queues the next item destined for that worker behind it, even if other
+# workers are idle. Use it when work items have uniform cost. Results are collected and
+# passed to a result handler running in a separate thread.
 #
 # @example Basic usage
 #   results = []
@@ -29,7 +34,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
@@ -42,12 +47,14 @@ class RactorPool
     def message: () -> String
   end
 
-  SHUTDOWN: ::Symbol
+  STRATEGIES: untyped
 
-  @collector: Thread?
+  SHUTDOWN: ::Symbol
 
   @error_collector: Thread?
 
+  @collector: Thread?
+
   @workers: Array[Ractor]
 
   @coordinator: Ractor?
@@ -56,6 +63,8 @@ class RactorPool
 
   @result_port: Ractor::Port?
 
+  @next_worker_index: Atom[Integer]?
+
   @shutdown: Atom[bool]
 
   @in_flight: Atom[Integer]
@@ -66,6 +75,8 @@ class RactorPool
 
   @name: String?
 
+  @strategy: Symbol
+
   @worker: ^(untyped) -> untyped
 
   @size: Integer
@@ -74,12 +85,14 @@ class RactorPool
   #
   # @param size [Integer] number of worker ractors to create
   # @param worker [Proc] a shareable proc that processes each work item
+  # @param strategy [Symbol] dispatch strategy, either +:coordinator+ (the default) or +:round_robin+
   # @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 strategy is not +:coordinator+ or +:round_robin+
   # @raise [ArgumentError] if on_error is given but is not a proc
   #
   # @example With result handler
@@ -88,13 +101,16 @@ class RactorPool
   # @example Without result handler
   #   pool = RactorPool.new(size: 4, worker: proc { it })
   #
+  # @example With round-robin strategy
+  #   pool = RactorPool.new(size: 4, strategy: :round_robin, worker: proc { it })
+  #
   # @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
+  # @rbs (?size: Integer, worker: ^(untyped) -> untyped, ?strategy: Symbol, ?name: String?, ?on_error: (^(Exception) -> void | nil)) ?{ (untyped) -> void } -> void
+  def initialize: (worker: ^(untyped) -> untyped, ?size: Integer, ?strategy: Symbol, ?name: String?, ?on_error: ^(Exception) -> void | nil) ?{ (untyped) -> void } -> void
 
   # Queues a work item to be processed by an available worker.
   #
@@ -137,8 +153,8 @@ class RactorPool
   def start_workers: () -> Array[Ractor]
 
   # @rbs () -> Thread?
-  def start_error_collector: () -> Thread?
+  def start_collector: () -> Thread?
 
   # @rbs () -> Thread?
-  def start_collector: () -> 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.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Joshua Young
@@ -73,8 +73,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+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
+summary: A thread-safe, lock-free pool of Ractor workers with coordinator or round-robin
+  dispatch for distributing work
 test_files: []