ractor-pool 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 13aa15dab296025cc8fa8348a4477bd8afd2db09b24ea4e13c43a17cca976cd2
-  data.tar.gz: b99432e86a0e93b69aa84867b869a0502469b402a297698599175442987cc23f
+  metadata.gz: 2d8741738f0de76db49cbbbaccc701b687af3df13ce9802205c7661a10519126
+  data.tar.gz: 337ce4d26b7735ec2517c2b88e76f2b11bef87124e3581a74772e68fbd3b6e57
 SHA512:
-  metadata.gz: 8f85b3c281484b9daf22e6e0fe2c195ca4a5a67640e3913d70f93cd109c022e3138cbae924477de09e2400c552b9b4c19eb386cf9b5b3479ec6bf60e382cbb4d
-  data.tar.gz: 6101a788de91cbe8f681cfa3c3c05556154061f0f96910e2474c1b083b5c283455d2ee1c525d30f8e73785148ad6392dbf1464f578cdb8b07670718b911bfba5
+  metadata.gz: 663d3b28aeab7e0341bbfd5d78540c670fbb74e3cfc89679572093067fc72396028d3b1637c224676d4c52d86aaafd688143e28499217f0b513c7d5035ba42c4
+  data.tar.gz: 6a9fc3ec933ece355f9bba48ac1de2980a3c105f0baaf2a13684ab74a54028daec5f2695dee25c4d970d3dc71f7bd066d207977424f8f199c44f8f61e9e6ae85

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 ## [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

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.1"
+  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 = []
@@ -48,16 +53,21 @@ 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?
@@ -69,12 +79,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
@@ -83,29 +95,35 @@ 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
     @collector = start_collector
     @error_collector = start_error_collector
@@ -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
@@ -175,7 +201,7 @@ class RactorPool
       @workers.each(&:join)
       @coordinator.join
     else
-      @workers.first.send(SHUTDOWN, move: true)
+      @workers.each { |worker| worker.send(SHUTDOWN, move: true) }
       @workers.each(&:join)
       @result_port&.send(SHUTDOWN, move: true)
     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 = []
@@ -42,6 +47,8 @@ class RactorPool
     def message: () -> String
   end
 
+  STRATEGIES: untyped
+
   SHUTDOWN: ::Symbol
 
   @error_collector: Thread?
@@ -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.
   #

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ractor-pool
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Joshua Young
@@ -75,6 +75,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 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: []