async 2.18.0 → 2.21.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6a94e07aa32d09643fca9fcdb1abed3ea1cc266561331b42f840b39cdb391673
-  data.tar.gz: ed364eb2cf2676401edc7a2d35eaab0f9f38e89aed1c66a1b03a0ae5e97a4441
+  metadata.gz: 6dda1de8f976c85bf6dcbd0156c27c30f85f88d5ffaf32f3397b9838aa920bab
+  data.tar.gz: 0f09cde08880db4456bc03e9a4351903b9a96ca7099e7305c76fdee7f8edc0ed
 SHA512:
-  metadata.gz: 353f270a396696c8a689e5e48657a0c06efb21a6a5d6ade30c68c54b7bd09c7b123466b6a382237deffa6f15ce186ececcf49b52d814cafff7bd4c446db3910c
-  data.tar.gz: 7390bd9fbef443a145dbbfd17f593cb0dffd91021ecb38cd3441a4a6ac7c04394197b512f177595739608a498f54c5619e14fd23ce0c0100a7b45eaa9b0bb3a6
+  metadata.gz: 980cd5e5832ddd71846785e10b23d18d11cb1f0eee33ccbdf33ed40feb4ac51dd99f7cf3d7f93055d0ad52de2abe0103c1b433d41f5bac1728c04435e35655db
+  data.tar.gz: d9c7c1c69e49acd89738f44900502bc83aea08341b84a9f8d9e02588261889a24a935dfa6509394514a575a4b17d8dcf0ca512518e8b0e089369a8fd37b44d52

data/lib/async/barrier.rb

@@ -9,11 +9,11 @@ require_relative "task"
 module Async
 	# A general purpose synchronisation primitive, which allows one task to wait for a number of other tasks to complete. It can be used in conjunction with {Semaphore}.
 	#
-	# @public Since `stable-v1`.
+	# @public Since *Async v1*.
 	class Barrier
 		# Initialize the barrier.
 		# @parameter parent [Task | Semaphore | Nil] The parent for holding any children tasks.
-		# @public Since `stable-v1`.
+		# @public Since *Async v1*.
 		def initialize(parent: nil)
 			@tasks = List.new
 			

data/lib/async/clock.rb

@@ -5,7 +5,7 @@
 
 module Async
 	# A convenient wrapper around the internal monotonic clock.
-	# @public Since `stable-v1`.
+	# @public Since *Async v1*.
 	class Clock
 		# Get the current elapsed monotonic time.
 		def self.now

data/lib/async/condition.rb

@@ -9,7 +9,7 @@ require_relative "list"
 
 module Async
 	# A synchronization primitive, which allows fibers to wait until a particular condition is (edge) triggered.
-	# @public Since `stable-v1`.
+	# @public Since *Async v1*.
 	class Condition
 		# Create a new condition.
 		def initialize

data/lib/async/console.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2024, by Samuel Williams.
+
+module Async
+	# Shims for the console gem, redirecting warnings and above to `Kernel#warn`.
+	#
+	# If you require this file, the `async` library will not depend on the `console` gem.
+	#
+	# That includes any gems that sit within the `Async` namespace.
+	#
+	# This is an experimental feature.
+	module Console
+		# Log a message at the debug level. The shim is silent.
+		def self.debug(...)
+		end
+		
+		# Log a message at the info level. The shim is silent.
+		def self.info(...)
+		end
+		
+		# Log a message at the warn level. The shim redirects to `Kernel#warn`.
+		def self.warn(*arguments, exception: nil, **options)
+			if exception
+				super(*arguments, exception.full_message, **options)
+			else
+				super(*arguments, **options)
+			end
+		end
+		
+		# Log a message at the error level. The shim redirects to `Kernel#warn`.
+		def self.error(...)
+			self.warn(...)
+		end
+		
+		# Log a message at the fatal level. The shim redirects to `Kernel#warn`.
+		def self.fatal(...)
+			self.warn(...)
+		end
+	end
+end

data/lib/async/idler.rb

@@ -7,7 +7,8 @@ module Async
 	# A load balancing mechanism that can be used process work when the system is idle.
 	class Idler
 		# Create a new idler.
-		# @public Since `stable-v2`.
+		#
+		# @public Since *Async v2*.
 		#
 		# @parameter maximum_load [Numeric] The maximum load before we start shedding work.
 		# @parameter backoff [Numeric] The initial backoff time, used for delaying work.

data/lib/async/notification.rb

@@ -7,7 +7,7 @@ require_relative "condition"
 
 module Async
 	# A synchronization primitive, which allows fibers to wait until a notification is received. Does not block the task which signals the notification. Waiting tasks are resumed on next iteration of the reactor.
-	# @public Since `stable-v1`.
+	# @public Since *Async v1*.
 	class Notification < Condition
 		# Signal to a given task that it should resume operations.
 		def signal(value = nil, task: Task.current)

data/lib/async/queue.rb

@@ -12,7 +12,7 @@ module Async
 	#
 	# It has a compatible interface with {Notification} and {Condition}, except that it's multi-value.
 	#
-	# @public Since `stable-v1`.
+	# @public Since *Async v1*.
 	class Queue
 		# Create a new queue.
 		#
@@ -99,7 +99,7 @@ module Async
 	end
 	
 	# A queue which limits the number of items that can be enqueued.
-	# @public Since `stable-v1`.
+	# @public Since *Async v1*.
 	class LimitedQueue < Queue
 		# Create a new limited queue.
 		#

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.
@@ -27,17 +32,17 @@ module Async
 		end
 		
 		# Whether the fiber scheduler is supported.
-		# @public Since `stable-v1`.
+		# @public Since *Async v1*.
 		def self.supported?
 			true
 		end
 		
 		# Create a new scheduler.
 		#
-		# @public Since `stable-v1`.
+		# @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,9 +54,19 @@ 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.
+		#
 		# @returns [Float] The load of the scheduler. 0.0 means no load, 1.0 means fully loaded or over-loaded.
 		def load
 			total_time = @busy_time + @idle_time
@@ -95,7 +110,7 @@ module Async
 		end
 		
 		# Terminate all child tasks and close the scheduler.
-		# @public Since `stable-v1`.
+		# @public Since *Async v1*.
 		def close
 			self.run_loop do
 				until self.terminate
@@ -111,11 +126,16 @@ module Async
 			
 			selector&.close
 			
+			worker_pool = @worker_pool
+			@worker_pool = nil
+			
+			worker_pool&.close
+			
 			consume
 		end
 		
 		# @returns [Boolean] Whether the scheduler has been closed.
-		# @public Since `stable-v1`.
+		# @public Since *Async v1*.
 		def closed?
 			@selector.nil?
 		end
@@ -167,7 +187,12 @@ module Async
 		end
 		
 		# 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
@@ -190,7 +215,13 @@ module Async
 			timer&.cancel!
 		end
 		
+		# Unblock a fiber that was previously blocked.
+		#
+		# @public Since *Async v2* and *Ruby v3.1*.
 		# @asynchronous May be called from any thread.
+		#
+		# @parameter blocker [Object] The object that was blocking the fiber.
+		# @parameter fiber [Fiber] The fiber to unblock.
 		def unblock(blocker, fiber)
 			# $stderr.puts "unblock(#{blocker}, #{fiber})"
 			
@@ -201,7 +232,12 @@ module Async
 			end
 		end
 		
-		# @asynchronous May be non-blocking..
+		# Sleep for the specified duration.
+		#
+		# @public Since *Async v2* and *Ruby v3.1*.
+		# @asynchronous May be non-blocking.
+		#
+		# @parameter duration [Numeric | Nil] The time in seconds to sleep, or if nil, indefinitely.
 		def kernel_sleep(duration = nil)
 			if duration
 				self.block(nil, duration)
@@ -210,7 +246,12 @@ module Async
 			end
 		end
 		
-		# @asynchronous May be non-blocking..
+		# Resolve the address of the given hostname.
+		#
+		# @public Since *Async v2*.
+		# @asynchronous May be non-blocking.
+		#
+		# @parameter hostname [String] The hostname to resolve.
 		def address_resolve(hostname)
 			# On some platforms, hostnames may contain a device-specific suffix (e.g. %en0). We need to strip this before resolving.
 			# See <https://github.com/socketry/async/issues/180> for more details.
@@ -218,7 +259,6 @@ module Async
 			::Resolv.getaddresses(hostname)
 		end
 		
-		
 		if IO.method_defined?(:timeout)
 			private def get_timeout(io)
 				io.timeout
@@ -229,7 +269,14 @@ module Async
 			end
 		end
 		
-		# @asynchronous May be non-blocking..
+		# Wait for the specified IO to become ready for the specified events.
+		#
+		# @public Since *Async v2*.
+		# @asynchronous May be non-blocking.
+		#
+		# @parameter io [IO] The IO object to wait on.
+		# @parameter events [Integer] The events to wait for, e.g. `IO::READABLE`, `IO::WRITABLE`, etc.
+		# @parameter timeout [Float | Nil] The maximum time to wait, or if nil, indefinitely.
 		def io_wait(io, events, timeout = nil)
 			fiber = Fiber.current
 			
@@ -251,6 +298,15 @@ module Async
 		end
 		
 		if ::IO::Event::Support.buffer?
+			# Read from the specified IO into the buffer.
+			#
+			# @public Since *Async v2* and Ruby with `IO::Buffer` support.
+			# @asynchronous May be non-blocking.
+			#
+			# @parameter io [IO] The IO object to read from.
+			# @parameter buffer [IO::Buffer] The buffer to read into.
+			# @parameter length [Integer] The minimum number of bytes to read.
+			# @parameter offset [Integer] The offset within the buffer to read into.
 			def io_read(io, buffer, length, offset = 0)
 				fiber = Fiber.current
 				
@@ -266,6 +322,15 @@ module Async
 			end
 			
 			if RUBY_ENGINE != "ruby" || RUBY_VERSION >= "3.3.1"
+				# Write the specified buffer to the IO.
+				#
+				# @public Since *Async v2* and *Ruby v3.3.1* with `IO::Buffer` support.
+				# @asynchronous May be non-blocking.
+				#
+				# @parameter io [IO] The IO object to write to.
+				# @parameter buffer [IO::Buffer] The buffer to write from.
+				# @parameter length [Integer] The minimum number of bytes to write.
+				# @parameter offset [Integer] The offset within the buffer to write from.
 				def io_write(io, buffer, length, offset = 0)
 					fiber = Fiber.current
 					
@@ -283,6 +348,10 @@ module Async
 		end
 		
 		# Wait for the specified process ID to exit.
+		#
+		# @public Since *Async v2*.
+		# @asynchronous May be non-blocking.
+		#
 		# @parameter pid [Integer] The process ID to wait for.
 		# @parameter flags [Integer] A bit-mask of flags suitable for `Process::Status.wait`.
 		# @returns [Process::Status] A process status instance.
@@ -335,7 +404,10 @@ module Async
 		end
 		
 		# Run one iteration of the event loop.
-		# Does not handle interrupts.
+		#
+		# @public Since *Async v1*.
+		# @asynchronous Must be invoked from blocking (root) fiber.
+		#
 		# @parameter timeout [Float | Nil] The maximum timeout, or if nil, indefinite.
 		# @returns [Boolean] Whether there is more work to do.
 		def run_once(timeout = nil)
@@ -354,6 +426,7 @@ module Async
 		end
 		
 		# Checks and clears the interrupted state of the scheduler.
+		#
 		# @returns [Boolean] Whether the reactor has been interrupted.
 		private def interrupted?
 			if @interrupted
@@ -368,7 +441,9 @@ module Async
 			return false
 		end
 		
-		# Stop all children, including transient children, ignoring any signals.
+		# Stop all children, including transient children.
+		#
+		# @public Since *Async v1*.
 		def stop
 			@children&.each do |child|
 				child.stop
@@ -387,7 +462,13 @@ module Async
 					end
 				end
 			rescue Interrupt => interrupt
+				# If an interrupt did occur during an iteration of the event loop, we need to handle it. More specifically, `self.stop` is not safe to interrupt without potentially corrupting the task tree.
 				Thread.handle_interrupt(::SignalException => :never) do
+					Console.debug(self) do |buffer|
+						buffer.puts "Scheduler interrupted: #{interrupt.inspect}"
+						self.print_hierarchy(buffer)
+					end
+					
 					self.stop
 				end
 				
@@ -395,10 +476,19 @@ module Async
 			end
 			
 			# If the event loop was interrupted, and we finished exiting normally (due to the interrupt), we need to re-raise the interrupt so that the caller can handle it too.
-			Kernel.raise(interrupt) if interrupt
+			if interrupt
+				Kernel.raise(interrupt)
+			end
 		end
 		
 		# Run the reactor until all tasks are finished. Proxies arguments to {#async} immediately before entering the loop, if a block is provided.
+		#
+		# Forwards all parameters to {#async} if a block is given.
+		#
+		# @public Since *Async v1*.
+		#
+		# @yields {|task| ...} The top level task, if a block is given.
+		# @returns [Task] The initial task that was scheduled into the reactor.
 		def run(...)
 			Kernel.raise ClosedError if @selector.nil?
 			
@@ -411,30 +501,23 @@ module Async
 			return initial_task
 		end
 		
-		# Start an asynchronous task within the specified reactor. The task will be
-		# executed until the first blocking call, at which point it will yield and
-		# and this method will return.
+		# Start an asynchronous task within the specified reactor. The task will be executed until the first blocking call, at which point it will yield and and this method will return.
 		#
-		# This is the main entry point for scheduling asynchronus tasks.
+		# @public Since *Async v1*.
+		# @asynchronous May context switch immediately to new task.
+		# @deprecated Use {#run} or {Task#async} instead.
 		#
 		# @yields {|task| ...} Executed within the task.
 		# @returns [Task] The task that was scheduled into the reactor.
-		# @deprecated With no replacement.
 		def async(*arguments, **options, &block)
+			# warn "Async::Scheduler#async is deprecated. Use `run` or `Task#async` instead.", uplevel: 1, category: :deprecated
+			
 			Kernel.raise ClosedError if @selector.nil?
 			
 			task = Task.new(Task.current? || self, **options, &block)
 			
-			# I want to take a moment to explain the logic of this.
-			# When calling an async block, we deterministically execute it until the
-			# first blocking operation. We don't *have* to do this - we could schedule
-			# it for later execution, but it's useful to:
-			# - Fail at the point of the method call where possible.
-			# - Execute determinstically where possible.
-			# - Avoid scheduler overhead if no blocking operation is performed.
 			task.run(*arguments)
 			
-			# Console.debug "Initial execution of task #{fiber} complete (#{result} -> #{fiber.alive?})..."
 			return task
 		end
 		
@@ -443,7 +526,14 @@ module Async
 		end
 		
 		# Invoke the block, but after the specified timeout, raise {TimeoutError} in any currenly blocking operation. If the block runs to completion before the timeout occurs or there are no non-blocking operations after the timeout expires, the code will complete without any exception.
+		#
+		# @public Since *Async v1*.
+		# @asynchronous May raise an exception at any interruption point (e.g. blocking operations).
+		#
 		# @parameter duration [Numeric] The time in seconds, in which the task should complete.
+		# @parameter exception [Class] The exception class to raise.
+		# @parameter message [String] The message to pass to the exception.
+		# @yields {|duration| ...} The block to execute with a timeout.
 		def with_timeout(duration, exception = TimeoutError, message = "execution expired", &block)
 			fiber = Fiber.current
 			
@@ -458,6 +548,15 @@ module Async
 			timer&.cancel!
 		end
 		
+		# Invoke the block, but after the specified timeout, raise the specified exception with the given message. If the block runs to completion before the timeout occurs or there are no non-blocking operations after the timeout expires, the code will complete without any exception.
+		#
+		# @public Since *Async v1* and *Ruby v3.1*. May be invoked from `Timeout.timeout`.
+		# @asynchronous May raise an exception at any interruption point (e.g. blocking operations).
+		#
+		# @parameter duration [Numeric] The time in seconds, in which the task should complete.
+		# @parameter exception [Class] The exception class to raise.
+		# @parameter message [String] The message to pass to the exception.
+		# @yields {|duration| ...} The block to execute with a timeout.
 		def timeout_after(duration, exception, message, &block)
 			with_timeout(duration, exception, message) do |timer|
 				yield duration

data/lib/async/semaphore.rb

@@ -7,7 +7,7 @@ require_relative "list"
 
 module Async
 	# A synchronization primitive, which limits access to a given resource.
-	# @public Since `stable-v1`.
+	# @public Since *Async v1*.
 	class Semaphore
 		# @parameter limit [Integer] The maximum number of times the semaphore can be acquired before it blocks.
 		# @parameter parent [Task | Semaphore | Nil] The parent for holding any children tasks.

data/lib/async/task.rb

@@ -8,7 +8,7 @@
 # Copyright, 2023, by Math Ieu.
 
 require "fiber"
-require "console/event/failure"
+require "console"
 
 require_relative "node"
 require_relative "condition"
@@ -40,7 +40,7 @@ module Async
 	end
 	
 	# Raised if a timeout occurs on a specific Fiber. Handled gracefully by `Task`.
-	# @public Since `stable-v1`.
+	# @public Since *Async v1*.
 	class TimeoutError < StandardError
 		# Create a new timeout error.
 		#
@@ -50,7 +50,7 @@ module Async
 		end
 	end
 	
-	# @public Since `stable-v1`.
+	# @public Since *Async v1*.
 	class Task < Node
 		# Raised when a child task is created within a task that has finished execution.
 		class FinishedError < RuntimeError
@@ -198,9 +198,7 @@ module Async
 				rescue => error
 					# I'm not completely happy with this overhead, but the alternative is to not log anything which makes debugging extremely difficult. Maybe we can introduce a debug wrapper which adds extra logging.
 					if @finished.nil?
-						Console::Event::Failure.for(error).emit(self, "Task may have ended with unhandled exception.", severity: :warn)
-					else
-						# Console::Event::Failure.for(error).emit(self, severity: :debug)
+						warn(self, "Task may have ended with unhandled exception.", exception: error)
 					end
 					
 					raise
@@ -212,6 +210,10 @@ module Async
 		
 		# Run an asynchronous task as a child of the current task.
 		#
+		# @public Since *Async v1*.
+		# @asynchronous May context switch immediately to the new task.
+		#
+		# @yields {|task| ...} in the context of the new task.
 		# @raises [FinishedError] If the task has already finished.
 		# @returns [Task] The child task.
 		def async(*arguments, **options, &block)
@@ -219,6 +221,13 @@ module Async
 			
 			task = Task.new(self, **options, &block)
 			
+			# When calling an async block, we deterministically execute it until the first blocking operation. We don't *have* to do this - we could schedule it for later execution, but it's useful to:
+			#
+			# - Fail at the point of the method call where possible.
+			# - Execute determinstically where possible.
+			# - Avoid scheduler overhead if no blocking operation is performed.
+			#
+			# There are different strategies (greedy vs non-greedy). We are currently using a greedy strategy.
 			task.run(*arguments)
 			
 			return task
@@ -304,7 +313,7 @@ module Async
 		# If stop is invoked a second time, it will be immediately executed.
 		#
 		# @yields {} The block of code to execute.
-		# @public Since `stable-v1`.
+		# @public Since *Async v1*.
 		def defer_stop
 			# Tri-state variable for controlling stop:
 			# - nil: defer_stop has not been called.
@@ -362,6 +371,10 @@ module Async
 		
 		private
 		
+		def warn(...)
+			Console.warn(...)
+		end
+		
 		# Finish the current task, moving any children to the parent.
 		def finish!
 			# Don't hold references to the fiber or block after the task has finished:

data/lib/async/version.rb

@@ -4,5 +4,5 @@
 # Copyright, 2017-2024, by Samuel Williams.
 
 module Async
-	VERSION = "2.18.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/lib/async/wrapper.rb

@@ -4,6 +4,8 @@
 # Copyright, 2017-2024, by Samuel Williams.
 # Copyright, 2017, by Kent Gruber.
 
+warn "Async::Wrapper is deprecated and will be removed on 2025-03-31. Please use native interfaces instead.", uplevel: 1, category: :deprecated
+
 module Async
 	# Represents an asynchronous IO within a reactor.
 	# @deprecated With no replacement. Prefer native interfaces.

data/lib/kernel/async.rb

@@ -19,7 +19,7 @@ module Kernel
 	# @yields {|task| ...} The block that will execute asynchronously.
 	# 	@parameter task [Async::Task] The task that is executing the given block.
 	#
-	# @public Since `stable-v1`.
+	# @public Since *Async v1*.
 	# @asynchronous May block until given block completes executing.
 	def Async(...)
 		if current = ::Async::Task.current?

data/lib/kernel/sync.rb

@@ -14,7 +14,7 @@ module Kernel
 	# @yields {|task| ...} The block that will execute asynchronously.
 	# 	@parameter task [Async::Task] The task that is executing the given block.
 	#
-	# @public Since `stable-v1`.
+	# @public Since *Async v1*.
 	# @asynchronous Will block until given block completes executing.
 	def Sync(annotation: nil, &block)
 		if task = ::Async::Task.current?

data/lib/metrics/provider/async/task.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2024, by Samuel Williams.
+
+require_relative "../../../async/task"
+require "metrics/provider"
+
+Metrics::Provider(Async::Task) do
+	ASYNC_TASK_SCHEDULED = Metrics.metric("async.task.scheduled", :counter, description: "The number of tasks scheduled.")
+	
+	def schedule(&block)
+		ASYNC_TASK_SCHEDULED.emit(1)
+		
+		super(&block)
+	end
+end

data/lib/metrics/provider/async.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2024, by Samuel Williams.
+
+require_relative "async/task"

data/lib/traces/provider/async/barrier.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2022, by Samuel Williams.
+
+require_relative "../../../async/barrier"
+require "traces/provider"
+
+Traces::Provider(Async::Barrier) do
+	def wait
+		attributes = {
+			"size" => self.size
+		}
+		
+		Traces.trace("async.barrier.wait", attributes: attributes) {super}
+	end
+end

data/lib/traces/provider/async/task.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2022, by Samuel Williams.
+
+require_relative "../../../async/task"
+require "traces/provider"
+
+Traces::Provider(Async::Task) do
+	def schedule(&block)
+		unless self.transient?
+			trace_context = Traces.trace_context
+		end
+		
+		super do
+			Traces.trace_context = trace_context
+			
+			if annotation = self.annotation
+				attributes = {
+					"annotation" => annotation
+				}
+			end
+			
+			Traces.trace("async.task", attributes: attributes) do
+				yield
+			end
+		end
+	end
+end

data/lib/traces/provider/async.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2024, by Samuel Williams.
+
+require_relative "async/task"
+require_relative "async/barrier"

data/readme.md

@@ -35,6 +35,19 @@ 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)
+
+### v2.19.0
+
+  - [Async::Scheduler Debugging](https://socketry.github.io/async/releases/index#async::scheduler-debugging)
+  - [Console Shims](https://socketry.github.io/async/releases/index#console-shims)
+
 ### v2.18.0
 
   - Add support for `Sync(annotation:)`, so that you can annotate the block with a description of what it does, even if it doesn't create a new task.

data/releases.md

@@ -1,5 +1,70 @@
 # 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
+
+Async now has [traces](https://github.com/socketry/traces) and [metrics](https://github.com/socketry/metrics) providers for various core classes. This allows you to emit traces and metrics to a suitable backend (including DataDog, New Relic, OpenTelemetry, etc.) for monitoring and debugging purposes.
+
+To take advantage of this feature, you will need to introduce your own `config/traces.rb` and `config/metrics.rb`. Async's own repository includes these files for testing purposes, you could copy them into your own project and modify them as needed.
+
+## v2.19.0
+
+### Async::Scheduler Debugging
+
+Occasionally on issues, I encounter people asking for help and I need more information. Pressing Ctrl-C to exit a hung program is common, but it usually doesn't provide enough information to diagnose the problem. Setting the `CONSOLE_LEVEL=debug` environment variable will now print additional information about the scheduler when you interrupt it, including a backtrace of the current tasks.
+
+    > CONSOLE_LEVEL=debug bundle exec ruby ./test.rb
+    ^C  0.0s    debug: Async::Reactor [oid=0x974] [ec=0x988] [pid=9116] [2024-11-08 14:12:03 +1300]
+                   | Scheduler interrupted: Interrupt
+                   | #<Async::Reactor:0x0000000000000974 1 children (running)>
+                   | 	#<Async::Task:0x000000000000099c /Users/samuel/Developer/socketry/async/lib/async/scheduler.rb:185:in `transfer' (running)>
+                   | 	→ /Users/samuel/Developer/socketry/async/lib/async/scheduler.rb:185:in `transfer'
+                   | 	  /Users/samuel/Developer/socketry/async/lib/async/scheduler.rb:185:in `block'
+                   | 	  /Users/samuel/Developer/socketry/async/lib/async/scheduler.rb:207:in `kernel_sleep'
+                   | 	  /Users/samuel/Developer/socketry/async/test.rb:7:in `sleep'
+                   | 	  /Users/samuel/Developer/socketry/async/test.rb:7:in `sleepy'
+                   | 	  /Users/samuel/Developer/socketry/async/test.rb:12:in `block in <top (required)>'
+                   | 	  /Users/samuel/Developer/socketry/async/lib/async/task.rb:197:in `block in run'
+                   | 	  /Users/samuel/Developer/socketry/async/lib/async/task.rb:420:in `block in schedule'
+    /Users/samuel/Developer/socketry/async/lib/async/scheduler.rb:317:in `select': Interrupt
+    ... (backtrace continues) ...
+
+This gives better visibility into what the scheduler is doing, and should help diagnose issues.
+
+### Console Shims
+
+The `async` gem depends on `console` gem, because my goal was to have good logging by default without thinking about it too much. However, some users prefer to avoid using the `console` gem for logging, so I've added an experimental set of shims which should allow you to bypass the `console` gem entirely.
+
+``` ruby
+require 'async/console'
+require 'async'
+
+Async{raise "Boom"}
+```
+
+Will now use `Kernel#warn` to print the task failure warning:
+
+    #<Async::Task:0x00000000000012d4 /home/samuel/Developer/socketry/async/lib/async/task.rb:104:in `backtrace' (running)>
+    Task may have ended with unhandled exception.
+    (irb):4:in `block in <top (required)>': Boom (RuntimeError)
+    	from /home/samuel/Developer/socketry/async/lib/async/task.rb:197:in `block in run'
+    	from /home/samuel/Developer/socketry/async/lib/async/task.rb:420:in `block in schedule'
+
 ## v2.18.0
 
   - Add support for `Sync(annotation:)`, so that you can annotate the block with a description of what it does, even if it doesn't create a new task.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async
 version: !ruby/object:Gem::Version
-  version: 2.18.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-10-29 00:00:00.000000000 Z
+date: 2024-11-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: console
@@ -71,14 +71,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.26'
+        version: '1.29'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.26'
+        version: '1.29'
 - !ruby/object:Gem::Dependency
   name: fiber-annotation
   requirement: !ruby/object:Gem::Requirement
@@ -125,6 +125,7 @@ files:
 - lib/async/clock.rb
 - lib/async/condition.md
 - lib/async/condition.rb
+- lib/async/console.rb
 - lib/async/idler.rb
 - lib/async/list.rb
 - lib/async/node.rb
@@ -140,9 +141,15 @@ 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
+- lib/metrics/provider/async.rb
+- lib/metrics/provider/async/task.rb
+- lib/traces/provider/async.rb
+- lib/traces/provider/async/barrier.rb
+- lib/traces/provider/async/task.rb
 - license.md
 - readme.md
 - releases.md
@@ -168,7 +175,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.8
+rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
 summary: A concurrency framework for Ruby.