async 2.21.0 → 2.21.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4a5bc2e233137c26a571123a0edc0cd22fe32278f780fe801c166a2c7968dc83
-  data.tar.gz: 2c2aab55da8cfe72e2806a6bb1e4a18e3b20d7162ff929bcb91de019eb9c6da3
+  metadata.gz: 6dda1de8f976c85bf6dcbd0156c27c30f85f88d5ffaf32f3397b9838aa920bab
+  data.tar.gz: 0f09cde08880db4456bc03e9a4351903b9a96ca7099e7305c76fdee7f8edc0ed
 SHA512:
-  metadata.gz: 9f3490b820e58aa4e6a3a95051bc36b699903f617918832f557b4a3369c7101a9c36cf878b34ab274caa1379591c30fef0f56cac79dbf1da482b16472c9cde1d
-  data.tar.gz: 8c911bdb5a50dadc299ee4d7ed0cd6d16371b84fe622fb1542190fc5a586f914dca4a5396de481f826c8606d547df831357f783f3ee67da3de18e49dd5ad7dd6
+  metadata.gz: 980cd5e5832ddd71846785e10b23d18d11cb1f0eee33ccbdf33ed40feb4ac51dd99f7cf3d7f93055d0ad52de2abe0103c1b433d41f5bac1728c04435e35655db
+  data.tar.gz: d9c7c1c69e49acd89738f44900502bc83aea08341b84a9f8d9e02588261889a24a935dfa6509394514a575a4b17d8dcf0ca512518e8b0e089369a8fd37b44d52

data/lib/async/scheduler.rb

@@ -7,6 +7,7 @@
 
 require_relative "clock"
 require_relative "task"
+require_relative "worker_pool"
 
 require "io/event"
 
@@ -16,6 +17,10 @@ require "resolv"
 module Async
 	# Handles scheduling of fibers. Implements the fiber scheduler interface.
 	class Scheduler < Node
+		DEFAULT_WORKER_POOL = ENV.fetch("ASYNC_SCHEDULER_DEFAULT_WORKER_POOL", nil).then do |value|
+			value == "true" ? true : nil
+		end
+		
 		# Raised when an operation is attempted on a closed scheduler.
 		class ClosedError < RuntimeError
 			# Create a new error.
@@ -37,7 +42,7 @@ module Async
 		# @public Since *Async v1*.
 		# @parameter parent [Node | Nil] The parent node to use for task hierarchy.
 		# @parameter selector [IO::Event::Selector] The selector to use for event handling.
-		def initialize(parent = nil, selector: nil)
+		def initialize(parent = nil, selector: nil, worker_pool: DEFAULT_WORKER_POOL)
 			super(parent)
 			
 			@selector = selector || ::IO::Event::Selector.new(Fiber.current)
@@ -49,6 +54,15 @@ module Async
 			@idle_time = 0.0
 			
 			@timers = ::IO::Event::Timers.new
+			if worker_pool == true
+				@worker_pool = WorkerPool.new
+			else
+				@worker_pool = worker_pool
+			end
+			
+			if @worker_pool
+				self.singleton_class.prepend(WorkerPool::BlockingOperationWait)
+			end
 		end
 		
 		# Compute the scheduler load according to the busy and idle times that are updated by the run loop.
@@ -112,6 +126,11 @@ module Async
 			
 			selector&.close
 			
+			worker_pool = @worker_pool
+			@worker_pool = nil
+			
+			worker_pool&.close
+			
 			consume
 		end
 		
@@ -169,8 +188,11 @@ module Async
 		
 		# Invoked when a fiber tries to perform a blocking operation which cannot continue. A corresponding call {unblock} must be performed to allow this fiber to continue.
 		#
-
+		# @public Since *Async v2*.
 		# @asynchronous May only be called on same thread as fiber scheduler.
+		#
+		# @parameter blocker [Object] The object that is blocking the fiber.
+		# @parameter timeout [Float | Nil] The maximum time to block, or if nil, indefinitely.
 		def block(blocker, timeout)
 			# $stderr.puts "block(#{blocker}, #{Fiber.current}, #{timeout})"
 			fiber = Fiber.current
@@ -338,25 +360,6 @@ module Async
 			return @selector.process_wait(Fiber.current, pid, flags)
 		end
 		
-		# Wait for the given work to be executed.
-		#
-		# @public Since *Async v2.19* and *Ruby v3.4*.
-		# @asynchronous May be non-blocking.
-		#
-		# @parameter work [Proc] The work to execute on a background thread.
-		# @returns [Object] The result of the work.
-		def blocking_operation_wait(work)
-			thread = Thread.new(&work)
-			
-			result = thread.join
-			
-			thread = nil
-			
-			return result
-		ensure
-			thread&.kill
-		end
-		
 		# Run one iteration of the event loop.
 		#
 		# When terminating the event loop, we already know we are finished. So we don't need to check the task tree. This is a logical requirement because `run_once` ignores transient tasks. For example, a single top level transient task is not enough to keep the reactor running, but during termination we must still process it in order to terminate child tasks.

data/lib/async/version.rb

@@ -4,5 +4,5 @@
 # Copyright, 2017-2024, by Samuel Williams.
 
 module Async
-	VERSION = "2.21.0"
+	VERSION = "2.21.1"
 end

data/lib/async/worker_pool.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2024, by Samuel Williams.
+
+require "etc"
+
+module Async
+	# A simple work pool that offloads work to a background thread.
+	#
+	# @private
+	class WorkerPool
+		module BlockingOperationWait
+			# Wait for the given work to be executed.
+			#
+			# @public Since *Async v2.19* and *Ruby v3.4*.
+			# @asynchronous May be non-blocking.
+			#
+			# @parameter work [Proc] The work to execute on a background thread.
+			# @returns [Object] The result of the work.
+			def blocking_operation_wait(work)
+				@worker_pool.call(work)
+			end
+		end
+		
+		class Promise
+			def initialize(work)
+				@work = work
+				@state = :pending
+				@value = nil
+				@guard = ::Mutex.new
+				@condition = ::ConditionVariable.new
+				@thread = nil
+			end
+			
+			def call
+				work = nil
+				
+				@guard.synchronize do
+					@thread = ::Thread.current
+					
+					return unless work = @work
+				end
+				
+				resolve(work.call)
+			rescue Exception => error
+				reject(error)
+			end
+			
+			private def resolve(value)
+				@guard.synchronize do
+					@work = nil
+					@thread = nil
+					@value = value
+					@state = :resolved
+					@condition.broadcast
+				end
+			end
+			
+			private def reject(error)
+				@guard.synchronize do
+					@work = nil
+					@thread = nil
+					@value = error
+					@state = :failed
+					@condition.broadcast
+				end
+			end
+			
+			def cancel
+				return unless @work
+				
+				@guard.synchronize do
+					@work = nil
+					@state = :cancelled
+					@thread&.raise(Interrupt)
+				end
+			end
+			
+			def wait
+				@guard.synchronize do
+					while @state == :pending
+						@condition.wait(@guard)
+					end
+					
+					if @state == :failed
+						raise @value
+					else
+						return @value
+					end
+				end
+			end
+		end
+		
+		# A handle to the work being done.
+		class Worker
+			def initialize
+				@work = ::Thread::Queue.new
+				@thread = ::Thread.new(&method(:run))
+			end
+			
+			def run
+				while work = @work.pop
+					work.call
+				end
+			end
+			
+			def close
+				if thread = @thread
+					@thread = nil
+					thread.kill
+				end
+			end
+			
+			# Call the work and notify the scheduler when it is done.
+			def call(work)
+				promise = Promise.new(work)
+				
+				@work.push(promise)
+				
+				begin
+					return promise.wait
+				ensure
+					promise.cancel
+				end
+			end
+		end
+		
+		# Create a new work pool.
+		#
+		# @parameter size [Integer] The number of threads to use.
+		def initialize(size: Etc.nprocessors)
+			@ready = ::Thread::Queue.new
+			
+			size.times do
+				@ready.push(Worker.new)
+			end
+		end
+		
+		# Close the work pool. Kills all outstanding work.
+		def close
+			if ready = @ready
+				@ready = nil
+				ready.close
+				
+				while worker = ready.pop
+					worker.close
+				end
+			end
+		end
+		
+		# Offload work to a thread.
+		#
+		# @parameter work [Proc] The work to be done.
+		def call(work)
+			if ready = @ready
+				worker = ready.pop
+				
+				begin
+					worker.call(work)
+				ensure
+					ready.push(worker)
+				end
+			else
+				raise RuntimeError, "No worker available!"
+			end
+		end
+	end
+end

data/readme.md

@@ -35,6 +35,10 @@ Please see the [project documentation](https://socketry.github.io/async/) for mo
 
 Please see the [project releases](https://socketry.github.io/async/releases/index) for all releases.
 
+### v2.21.1
+
+  - [Worker Pool](https://socketry.github.io/async/releases/index#worker-pool)
+
 ### v2.20.0
 
   - [Traces and Metrics Providers](https://socketry.github.io/async/releases/index#traces-and-metrics-providers)

data/releases.md

@@ -1,5 +1,19 @@
 # Releases
 
+## v2.21.1
+
+### Worker Pool
+
+Ruby 3.4 will feature a new fiber scheduler hook, `blocking_operation_wait` which allows the scheduler to redirect the work given to `rb_nogvl` to a worker pool.
+
+The Async scheduler optionally supports this feature using a worker pool, by using the following environment variable:
+
+    ASYNC_SCHEDULER_DEFAULT_WORKER_POOL=true
+
+This will cause the scheduler to use a worker pool for general blocking operations, rather than blocking the event loop.
+
+It should be noted that this isn't a net win, as the overhead of using a worker pool can be significant compared to the `rb_nogvl` work. As such, it is recommended to benchmark your application with and without the worker pool to determine if it is beneficial.
+
 ## v2.20.0
 
 ### Traces and Metrics Providers

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async
 version: !ruby/object:Gem::Version
-  version: 2.21.0
+  version: 2.21.1
 platform: ruby
 authors:
 - Samuel Williams
@@ -63,7 +63,7 @@ cert_chain:
   Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
   voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
   -----END CERTIFICATE-----
-date: 2024-11-21 00:00:00.000000000 Z
+date: 2024-11-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: console
@@ -141,6 +141,7 @@ files:
 - lib/async/version.rb
 - lib/async/waiter.md
 - lib/async/waiter.rb
+- lib/async/worker_pool.rb
 - lib/async/wrapper.rb
 - lib/kernel/async.rb
 - lib/kernel/sync.rb