async 2.12.1 → 2.16.1

data/lib/async/scheduler.rb

@@ -16,7 +16,11 @@ require 'resolv'
 module Async
 	# Handles scheduling of fibers. Implements the fiber scheduler interface.
 	class Scheduler < Node
+		# Raised when an operation is attempted on a closed scheduler.
 		class ClosedError < RuntimeError
+			# Create a new error.
+			#
+			# @parameter message [String] The error message.
 			def initialize(message = "Scheduler is closed!")
 				super
 			end
@@ -28,6 +32,11 @@ module Async
 			true
 		end
 		
+		# Create a new scheduler.
+		#
+		# @public Since `stable-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)
 			super(parent)
 			
@@ -62,43 +71,46 @@ module Async
 				return @busy_time / total_time
 			end
 		end
-		
-		def scheduler_close
+	
+		# Invoked when the fiber scheduler is being closed.
+		#
+		# Executes the run loop until all tasks are finished, then closes the scheduler.
+		def scheduler_close(error = $!)
 			# If the execution context (thread) was handling an exception, we want to exit as quickly as possible:
-			unless $!
+			unless error
 				self.run
 			end
 		ensure
 			self.close
 		end
 		
-		# Terminate the scheduler. We deliberately ignore interrupts here, as this code can be called from an interrupt, and we don't want to be interrupted while cleaning up.
+		# Terminate all child tasks.
 		def terminate
-			Thread.handle_interrupt(::Interrupt => :never) do
-				super
+			# If that doesn't work, take more serious action:
+			@children&.each do |child|
+				child.terminate
 			end
+			
+			return @children.nil?
 		end
 		
+		# Terminate all child tasks and close the scheduler.
 		# @public Since `stable-v1`.
 		def close
-			# It's critical to stop all tasks. Otherwise they might be holding on to resources which are never closed/released correctly.
-			until self.terminate
-				self.run_once!
+			self.run_loop do
+				until self.terminate
+					self.run_once!
+				end
 			end
 			
 			Kernel.raise "Closing scheduler with blocked operations!" if @blocked > 0
-			
-			# We depend on GVL for consistency:
-			# @guard.synchronize do
-			
+		ensure
 			# We want `@selector = nil` to be a visible side effect from this point forward, specifically in `#interrupt` and `#unblock`. If the selector is closed, then we don't want to push any fibers to it.
 			selector = @selector
 			@selector = nil
 			
 			selector&.close
 			
-			# end
-			
 			consume
 		end
 		
@@ -108,6 +120,7 @@ module Async
 			@selector.nil?
 		end
 		
+		# @returns [String] A description of the scheduler.
 		def to_s
 			"\#<#{self.description} #{@children&.size || 0} children (#{stopped? ? 'stopped' : 'running'})>"
 		end
@@ -135,10 +148,20 @@ module Async
 			@selector.push(fiber)
 		end
 		
-		def raise(*arguments)
-			@selector.raise(*arguments)
+		# Raise an exception on a specified fiber with the given arguments.
+		#
+		# This internally schedules the current fiber to be ready, before raising the exception, so that it will later resume execution.
+		#
+		# @parameter fiber [Fiber] The fiber to raise the exception on.
+		# @parameter *arguments [Array] The arguments to pass to the fiber.
+		def raise(...)
+			@selector.raise(...)
 		end
 		
+		# Resume execution of the specified fiber.
+		#
+		# @parameter fiber [Fiber] The fiber to resume.
+		# @parameter arguments [Array] The arguments to pass to the fiber.
 		def resume(fiber, *arguments)
 			@selector.resume(fiber, *arguments)
 		end
@@ -218,7 +241,7 @@ module Async
 			elsif timeout = get_timeout(io)
 				# Otherwise, if we default to the io's timeout, we raise an exception:
 				timer = @timers.after(timeout) do
-					fiber.raise(::IO::TimeoutError, "Timeout while waiting for IO to become ready!")
+					fiber.raise(::IO::TimeoutError, "Timeout (#{timeout}s) while waiting for IO to become ready!")
 				end
 			end
 			
@@ -233,7 +256,7 @@ module Async
 				
 				if timeout = get_timeout(io)
 					timer = @timers.after(timeout) do
-						fiber.raise(::IO::TimeoutError, "Timeout while waiting for IO to become readable!")
+						fiber.raise(::IO::TimeoutError, "Timeout (#{timeout}s) while waiting for IO to become readable!")
 					end
 				end
 				
@@ -248,7 +271,7 @@ module Async
 					
 					if timeout = get_timeout(io)
 						timer = @timers.after(timeout) do
-							fiber.raise(::IO::TimeoutError, "Timeout while waiting for IO to become writable!")
+							fiber.raise(::IO::TimeoutError, "Timeout (#{timeout}s) while waiting for IO to become writable!")
 						end
 					end
 					
@@ -268,28 +291,13 @@ module Async
 			return @selector.process_wait(Fiber.current, pid, flags)
 		end
 		
-		# Run one iteration of the event loop.
-		# Does not handle interrupts.
-		# @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)
-			Kernel::raise "Running scheduler on non-blocking fiber!" unless Fiber.blocking?
-			
-			# If we are finished, we stop the task tree and exit:
-			if self.finished?
-				return false
-			end
-			
-			return run_once!(timeout)
-		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.
 		#
 		# @parameter timeout [Float | Nil] The maximum timeout, or if nil, indefinite.
 		# @returns [Boolean] Whether there is more work to do.
-		private def run_once!(timeout = 0)
+		private def run_once!(timeout = nil)
 			start_time = Async::Clock.now
 			
 			interval = @timers.wait_interval
@@ -326,6 +334,25 @@ module Async
 			return true
 		end
 		
+		# Run one iteration of the event loop.
+		# Does not handle interrupts.
+		# @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)
+			Kernel.raise "Running scheduler on non-blocking fiber!" unless Fiber.blocking?
+			
+			if self.finished?
+				self.stop
+			end
+			
+			# If we are finished, we stop the task tree and exit:
+			if @children.nil?
+				return false
+			end
+			
+			return run_once!(timeout)
+		end
+		
 		# Checks and clears the interrupted state of the scheduler.
 		# @returns [Boolean] Whether the reactor has been interrupted.
 		private def interrupted?
@@ -341,22 +368,22 @@ module Async
 			return false
 		end
 		
-		# Run the reactor until all tasks are finished. Proxies arguments to {#async} immediately before entering the loop, if a block is provided.
-		def run(...)
-			Kernel::raise ClosedError if @selector.nil?
-			
-			initial_task = self.async(...) if block_given?
+		# Stop all children, including transient children, ignoring any signals.
+		def stop
+			@children&.each do |child|
+				child.stop
+			end
+		end
+		
+		private def run_loop(&block)
 			interrupt = nil
 			
 			begin
 				# In theory, we could use Exception here to be a little bit safer, but we've only shown the case for SignalException to be a problem, so let's not over-engineer this.
 				Thread.handle_interrupt(::SignalException => :never) do
-					while true
-						# If we are interrupted, we need to exit:
-						break if self.interrupted?
-						
+					until self.interrupted?
 						# If we are finished, we need to exit:
-						break unless self.run_once
+						break unless yield
 					end
 				end
 			rescue Interrupt => interrupt
@@ -368,11 +395,20 @@ 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
+			Kernel.raise(interrupt) if interrupt
+		end
+		
+		# Run the reactor until all tasks are finished. Proxies arguments to {#async} immediately before entering the loop, if a block is provided.
+		def run(...)
+			Kernel.raise ClosedError if @selector.nil?
+			
+			initial_task = self.async(...) if block_given?
+			
+			self.run_loop do
+				run_once
+			end
 			
 			return initial_task
-		ensure
-			Console.debug(self) {"Exiting run-loop because #{$! ? $! : 'finished'}."}
 		end
 		
 		# Start an asynchronous task within the specified reactor. The task will be
@@ -385,7 +421,7 @@ module Async
 		# @returns [Task] The task that was scheduled into the reactor.
 		# @deprecated With no replacement.
 		def async(*arguments, **options, &block)
-			Kernel::raise ClosedError if @selector.nil?
+			Kernel.raise ClosedError if @selector.nil?
 			
 			task = Task.new(Task.current? || self, **options, &block)
 			

data/lib/async/task.rb

@@ -13,18 +13,26 @@ require 'console/event/failure'
 require_relative 'node'
 require_relative 'condition'
 
+Fiber.attr_accessor :async_task
+
 module Async
 	# Raised when a task is explicitly stopped.
 	class Stop < Exception
+		# Used to defer stopping the current task until later.
 		class Later
+			# Create a new stop later operation.
+			#
+			# @parameter task [Task] The task to stop later.
 			def initialize(task)
 				@task = task
 			end
 			
+			# @returns [Boolean] Whether the task is alive.
 			def alive?
 				true
 			end
 			
+			# Transfer control to the operation - this will stop the task.
 			def transfer
 				@task.stop
 			end
@@ -34,6 +42,9 @@ module Async
 	# Raised if a timeout occurs on a specific Fiber. Handled gracefully by `Task`.
 	# @public Since `stable-v1`.
 	class TimeoutError < StandardError
+		# Create a new timeout error.
+		#
+		# @parameter message [String] The error message.
 		def initialize(message = "execution expired")
 			super
 		end
@@ -41,7 +52,11 @@ module Async
 	
 	# @public Since `stable-v1`.
 	class Task < Node
+		# Raised when a child task is created within a task that has finished execution.
 		class FinishedError < RuntimeError
+			# Create a new finished error.
+			#
+			# @parameter message [String] The error message.
 			def initialize(message = "Cannot create child task within a task that has finished execution!")
 				super
 			end
@@ -52,6 +67,13 @@ module Async
 			Fiber.scheduler.transfer
 		end
 		
+		# Run the given block of code in a task, asynchronously, in the given scheduler.
+		def self.run(scheduler, *arguments, **options, &block)
+			self.new(scheduler, **options, &block).tap do |task|
+				task.run(*arguments)
+			end
+		end
+		
 		# Create a new task.
 		# @parameter reactor [Reactor] the reactor this task will run within.
 		# @parameter parent [Task] the parent task.
@@ -72,14 +94,21 @@ module Async
 			@defer_stop = nil
 		end
 		
+		# @returns [Scheduler] The scheduler for this task.
 		def reactor
 			self.root
 		end
 		
+		# @returns [Array(Thread::Backtrace::Location) | Nil] The backtrace of the task, if available.
 		def backtrace(*arguments)
 			@fiber&.backtrace(*arguments)
 		end
 		
+		# Annotate the task with a description.
+		#
+		# This will internally try to annotate the fiber if it is running, otherwise it will annotate the task itself.
+		#
+		# @parameter annotation [String] The description to annotate the task with.
 		def annotate(annotation, &block)
 			if @fiber
 				@fiber.annotate(annotation, &block)
@@ -88,6 +117,7 @@ module Async
 			end
 		end
 		
+		# @returns [Object] The annotation of the task.
 		def annotation
 			if @fiber
 				@fiber.annotation
@@ -96,6 +126,7 @@ module Async
 			end
 		end
 		
+		# @returns [String] A description of the task and it's current status.
 		def to_s
 			"\#<#{self.description} (#{@status})>"
 		end
@@ -115,10 +146,10 @@ module Async
 			Fiber.scheduler.yield
 		end
 		
-		# @attr fiber [Fiber] The fiber which is being used for the execution of this task.
+		# @attribute [Fiber] The fiber which is being used for the execution of this task.
 		attr :fiber
 		
-		# Whether the internal fiber is alive, i.e. it 
+		# @returns [Boolean] Whether the internal fiber is alive, i.e. it is actively executing.
 		def alive?
 			@fiber&.alive?
 		end
@@ -130,38 +161,49 @@ module Async
 			super && @block.nil? && @fiber.nil?
 		end
 		
-		# Whether the task is running.
-		# @returns [Boolean]
+		# @returns [Boolean] Whether the task is running.
 		def running?
 			@status == :running
 		end
 		
+		# @returns [Boolean] Whether the task failed with an exception.
 		def failed?
 			@status == :failed
 		end
 		
-		# The task has been stopped
+		# @returns [Boolean] Whether the task has been stopped.
 		def stopped?
 			@status == :stopped
 		end
 		
-		# The task has completed execution and generated a result.
+		# @returns [Boolean] Whether the task has completed execution and generated a result.
 		def completed?
 			@status == :completed
 		end
 		
 		alias complete? completed?
 		
-		# @attr status [Symbol] The status of the execution of the fiber, one of `:initialized`, `:running`, `:complete`, `:stopped` or `:failed`.
+		# @attribute [Symbol] The status of the execution of the task, one of `:initialized`, `:running`, `:complete`, `:stopped` or `:failed`.
 		attr :status
 		
 		# Begin the execution of the task.
+		#
+		# @raises [RuntimeError] If the task is already running.
 		def run(*arguments)
 			if @status == :initialized
 				@status = :running
 				
 				schedule do
 					@block.call(self, *arguments)
+				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)
+					end
+					
+					raise
 				end
 			else
 				raise RuntimeError, "Task already running!"
@@ -169,6 +211,9 @@ module Async
 		end
 		
 		# Run an asynchronous task as a child of the current task.
+		#
+		# @raises [FinishedError] If the task has already finished.
+		# @returns [Task] The child task.
 		def async(*arguments, **options, &block)
 			raise FinishedError if self.finished?
 			
@@ -215,15 +260,18 @@ module Async
 				return stopped!
 			end
 			
-			# If we are deferring stop...
-			if @defer_stop == false
-				# Don't stop now... but update the state so we know we need to stop later.
-				@defer_stop = true
-				return false
-			end
-			
 			# If the fiber is alive, we need to stop it:
 			if @fiber&.alive?
+				# As the task is now exiting, we want to ensure the event loop continues to execute until the task finishes.
+				self.transient = false
+				
+				# If we are deferring stop...
+				if @defer_stop == false
+					# Don't stop now... but update the state so we know we need to stop later.
+					@defer_stop = true
+					return false
+				end
+				
 				if self.current?
 					# If the fiber is current, and later is `true`, we need to schedule the fiber to be stopped later, as it's currently invoking `stop`:
 					if later
@@ -238,7 +286,7 @@ module Async
 					begin
 						# There is a chance that this will stop the fiber that originally called stop. If that happens, the exception handling in `#stopped` will rescue the exception and re-raise it later.
 						Fiber.scheduler.raise(@fiber, Stop)
-					rescue FiberError
+					rescue FiberError => error
 						# In some cases, this can cause a FiberError (it might be resumed already), so we schedule it to be stopped later:
 						Fiber.scheduler.push(Stop::Later.new(self))
 					end
@@ -263,19 +311,23 @@ module Async
 			# - false: defer_stop has been called and we are not stopping.
 			# - true: defer_stop has been called and we will stop when exiting the block.
 			if @defer_stop.nil?
-				# If we are not deferring stop already, we can defer it now:
-				@defer_stop = false
-				
 				begin
+					# If we are not deferring stop already, we can defer it now:
+					@defer_stop = false
+					
 					yield
 				rescue Stop
 					# If we are exiting due to a stop, we shouldn't try to invoke stop again:
 					@defer_stop = nil
 					raise
 				ensure
+					defer_stop = @defer_stop
+					
+					# We need to ensure the state is reset before we exit the block:
+					@defer_stop = nil
+					
 					# If we were asked to stop, we should do so now:
-					if @defer_stop
-						@defer_stop = nil
+					if defer_stop
 						raise Stop, "Stopping current task (was deferred)!"
 					end
 				end
@@ -285,19 +337,25 @@ module Async
 			end
 		end
 		
+		# @returns [Boolean] Whether stop has been deferred.
+		def stop_deferred?
+			@defer_stop
+		end
+		
 		# Lookup the {Task} for the current fiber. Raise `RuntimeError` if none is available.
 		# @returns [Task]
 		# @raises[RuntimeError] If task was not {set!} for the current fiber.
 		def self.current
-			Thread.current[:async_task] or raise RuntimeError, "No async task available!"
+			Fiber.current.async_task or raise RuntimeError, "No async task available!"
 		end
 		
 		# Check if there is a task defined for the current fiber.
-		# @returns [Task | Nil]
+		# @returns [Interface(:async) | Nil]
 		def self.current?
-			Thread.current[:async_task]
+			Fiber.current.async_task
 		end
 		
+		# @returns [Boolean] Whether this task is the currently executing task.
 		def current?
 			Fiber.current.equal?(@fiber)
 		end
@@ -326,21 +384,10 @@ module Async
 			@status = :completed
 		end
 		
-		# This is a very tricky aspect of tasks to get right. I've modelled it after `Thread` but it's slightly different in that the exception can propagate back up through the reactor. If the user writes code which raises an exception, that exception should always be visible, i.e. cause a failure. If it's not visible, such code fails silently and can be very difficult to debug.
-		def failed!(exception = false, propagate = true)
+		# State transition into the failed state.
+		def failed!(exception = false)
 			@result = exception
 			@status = :failed
-			
-			if exception
-				if propagate
-					raise exception
-				elsif @finished.nil?
-					# If no one has called wait, we log this as a warning:
-					Console::Event::Failure.for(exception).emit(self, "Task may have ended with unhandled exception.", severity: :warn)
-				else
-					Console::Event::Failure.for(exception).emit(self, severity: :debug)
-				end
-			end
 		end
 		
 		def stopped!
@@ -371,30 +418,26 @@ module Async
 		
 		def schedule(&block)
 			@fiber = Fiber.new(annotation: self.annotation) do
-				set!
-				
 				begin
 					completed!(yield)
-					# Console.debug(self) {"Task was completed with #{@children.size} children!"}
 				rescue Stop
 					stopped!
 				rescue StandardError => error
-					failed!(error, false)
+					failed!(error)
 				rescue Exception => exception
-					failed!(exception, true)
+					failed!(exception)
+					
+					# This is a critical failure, we should stop the reactor:
+					raise
 				ensure
 					# Console.info(self) {"Task ensure $! = #{$!} with #{@children&.size.inspect} children!"}
 					finish!
 				end
 			end
 			
+			@fiber.async_task = self
+			
 			self.root.resume(@fiber)
 		end
-		
-		# Set the current fiber's `:async_task` to this task.
-		def set!
-			# This is actually fiber-local:
-			Thread.current[:async_task] = self
-		end
 	end
 end

data/lib/async/variable.rb

@@ -1,17 +1,26 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2021-2022, by Samuel Williams.
+# Copyright, 2021-2024, by Samuel Williams.
 
 require_relative 'condition'
 
 module Async
+	# A synchronization primitive that allows one task to wait for another task to resolve a value.
 	class Variable
+		# Create a new variable.
+		#
+		# @parameter condition [Condition] The condition to use for synchronization.
 		def initialize(condition = Condition.new)
 			@condition = condition
 			@value = nil
 		end
 		
+		# Resolve the value.
+		#
+		# Signals all waiting tasks.
+		#
+		# @parameter value [Object] The value to resolve.
 		def resolve(value = true)
 			@value = value
 			condition = @condition
@@ -22,17 +31,23 @@ module Async
 			condition.signal(value)
 		end
 		
+		alias value= resolve
+		
+		# Whether the value has been resolved.
+		#
+		# @returns [Boolean] Whether the value has been resolved.
 		def resolved?
 			@condition.nil?
 		end
 		
-		def value
+		# Wait for the value to be resolved.
+		#
+		# @returns [Object] The resolved value.
+		def wait
 			@condition&.wait
 			return @value
 		end
 		
-		def wait
-			self.value
-		end
+		alias value wait
 	end
 end

data/lib/async/version.rb

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

data/lib/async/waiter.rb

@@ -1,11 +1,16 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2022, by Samuel Williams.
+# Copyright, 2022-2024, by Samuel Williams.
+# Copyright, 2024, by Patrik Wenger.
 
 module Async
 	# A composable synchronization primitive, which allows one task to wait for a number of other tasks to complete. It can be used in conjunction with {Semaphore} and/or {Barrier}.
 	class Waiter
+		# Create a waiter instance.
+		#
+		# @parameter parent [Interface(:async) | Nil] The parent task to use for asynchronous operations.
+		# @parameter finished [Async::Condition] The condition to signal when a task completes.
 		def initialize(parent: nil, finished: Async::Condition.new)
 			@finished = finished
 			@done = []
@@ -15,8 +20,8 @@ module Async
 		
 		# Execute a child task and add it to the waiter.
 		# @asynchronous Executes the given block concurrently.
-		def async(parent: (@parent or Task.current), &block)
-			parent.async do |task|
+		def async(parent: (@parent or Task.current), **options, &block)
+			parent.async(**options) do |task|
 				yield(task)
 			ensure
 				@done << task