async 2.2.1 → 2.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 74fa09c162a2702195d38adcb921dec7c9b53563a81b5d7cc117bf3a3f1402f3
-  data.tar.gz: 37e7fae58da9e1a0ca928a1c9f34b376da95b8cdfcb89949fb9200dfb7253351
+  metadata.gz: 042a45792628d56b89e02200e38d6d00fb16c5311b95c3dae7d52607aef8108a
+  data.tar.gz: 6e7b3271d484ee3aabe395996ca987b1e0043d6d8710b3b706688993df43c916
 SHA512:
-  metadata.gz: 9b17a23c9c0d7affeb9c75d8c1058fb0c25d2c8ebac6568ebf5834885f6379dc799c3bc9f92699441cc8cfd387cadbce993c52ca5b576fcedc0e1d68a4fd9c21
-  data.tar.gz: 80a3a72ab5e9c49af4018a34564c7a7d72314dd9c640f306a4c7eab8b99fa9682a55135eb0b67614c370a4526908832b91cf94436089f4b48670a12d8b4a2896
+  metadata.gz: 49ea21f4f81b9e566119265b834ecbfb4de8db83788370e18d3d27b14e7a2ec972960f67301139dd61111f13843325264412bf096b5b33cafff910630b1663cb
+  data.tar.gz: 151eee11c70bf263c72cae52142168449ba38cd68a00ad302c2c9fcf53088de65784f35193971628e6c1ddb9d7efab9677359040ed19e13cde1f846670fd9b3e

data/lib/async/barrier.md

@@ -7,6 +7,7 @@ require 'async'
 require 'async/barrier'
 
 Sync do
+	Console.logger.info("Barrier Example: sleep sort.")
 	barrier = Async::Barrier.new
 	
 	# Generate an array of 10 numbers:
@@ -31,6 +32,7 @@ end
 ### Output
 
 ~~~
-0.0s     info: Sorted [ec=0x104] [pid=50291]
-						 | [0, 0, 0, 0, 1, 2, 2, 3, 6, 6]
+0.0s     info: Barrier Example: sleep sort.
+9.0s     info: Sorted
+             | [3, 3, 3, 4, 4, 5, 5, 5, 8, 9]
 ~~~

data/lib/async/barrier.rb

@@ -3,35 +3,47 @@
 # Released under the MIT License.
 # Copyright, 2019-2022, by Samuel Williams.
 
+require_relative 'list'
 require_relative 'task'
 
 module Async
-	# A synchronization primitive, which allows one task to wait for a number of other tasks to complete. It can be used in conjunction with {Semaphore}.
+	# 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`.
 	class Barrier
 		# Initialize the barrier.
 		# @parameter parent [Task | Semaphore | Nil] The parent for holding any children tasks.
 		# @public Since `stable-v1`.
 		def initialize(parent: nil)
-			@tasks = []
+			@tasks = List.new
 			
 			@parent = parent
 		end
 		
-		# All tasks which have been invoked into the barrier.
-		attr :tasks
+		class TaskNode < List::Node
+			def initialize(task)
+				@task = task
+			end
+			
+			attr :task
+		end
 		
-		# The number of tasks currently held by the barrier.
+		private_constant :TaskNode
+		
+		# Number of tasks being held by the barrier.
 		def size
 			@tasks.size
 		end
 		
+		# All tasks which have been invoked into the barrier.
+		attr :tasks
+		
 		# Execute a child task and add it to the barrier.
 		# @asynchronous Executes the given block concurrently.
 		def async(*arguments, parent: (@parent or Task.current), **options, &block)
 			task = parent.async(*arguments, **options, &block)
 			
-			@tasks << task
+			@tasks.append(TaskNode.new(task))
 			
 			return task
 		end
@@ -42,21 +54,15 @@ module Async
 			@tasks.empty?
 		end
 		
-		# Wait for all tasks.
+		# Wait for all tasks to complete by invoking {Task#wait} on each waiting task, which may raise an error. As long as the task has completed, it will be removed from the barrier.
 		# @asynchronous Will wait for tasks to finish executing.
 		def wait
-			# TODO: This would be better with linked list.
-			while @tasks.any?
-				task = @tasks.first
-				
+			@tasks.each do |waiting|
+				task = waiting.task
 				begin
 					task.wait
 				ensure
-					# We don't know for sure that the exception was due to the task completion.
-					unless task.running?
-						# Remove the task from the waiting list if it's finished:
-						@tasks.shift if @tasks.first == task
-					end
+					@tasks.remove?(waiting) unless task.alive?
 				end
 			end
 		end
@@ -64,9 +70,9 @@ module Async
 		# Stop all tasks held by the barrier.
 		# @asynchronous May wait for tasks to finish executing.
 		def stop
-			# We have to be careful to avoid enumerating tasks while adding/removing to it:
-			tasks = @tasks.dup
-			tasks.each(&:stop)
+			@tasks.each do |waiting|
+				waiting.task.stop
+			end
 		end
 	end
 end

data/lib/async/condition.md

@@ -25,7 +25,7 @@ end
 ### Output
 
 ~~~
-0.0s     info: Waiting for condition... [ec=0x3c] [pid=47943]
-1.0s     info: Signalling condition... [ec=0x64] [pid=47943]
-1.0s     info: Condition was signalled: Hello World [ec=0x3c] [pid=47943]
+0.0s     info: Waiting for condition...
+1.0s     info: Signalling condition...
+1.0s     info: Condition was signalled: Hello World
 ~~~

data/lib/async/condition.rb

@@ -5,41 +5,38 @@
 # Copyright, 2017, by Kent Gruber.
 
 require 'fiber'
-require_relative 'node'
+require_relative 'list'
 
 module Async
 	# A synchronization primitive, which allows fibers to wait until a particular condition is (edge) triggered.
 	# @public Since `stable-v1`.
 	class Condition
 		def initialize
-			@waiting = []
+			@waiting = List.new
 		end
 		
-		Queue = Struct.new(:fiber) do
-			def transfer(*arguments)
-				fiber&.transfer(*arguments)
+		class FiberNode < List::Node
+			def initialize(fiber)
+				@fiber = fiber
 			end
 			
-			def alive?
-				fiber&.alive?
+			def transfer(*arguments)
+				@fiber.transfer(*arguments)
 			end
 			
-			def nullify
-				self.fiber = nil
+			def alive?
+				@fiber.alive?
 			end
 		end
 		
-		private_constant :Queue
+		private_constant :FiberNode
 		
 		# Queue up the current fiber and wait on yielding the task.
 		# @returns [Object]
 		def wait
-			queue = Queue.new(Fiber.current)
-			@waiting << queue
-			
-			Fiber.scheduler.transfer
-		ensure
-			queue.nullify
+			@waiting.stack(FiberNode.new(Fiber.current)) do
+				Fiber.scheduler.transfer
+			end
 		end
 		
 		# Is any fiber waiting on this notification?
@@ -51,8 +48,9 @@ module Async
 		# Signal to a given task that it should resume operations.
 		# @parameter value [Object | Nil] The value to return to the waiting fibers.
 		def signal(value = nil)
-			waiting = @waiting
-			@waiting = []
+			return if @waiting.empty?
+			
+			waiting = self.exchange
 			
 			waiting.each do |fiber|
 				Fiber.scheduler.resume(fiber, value) if fiber.alive?
@@ -60,5 +58,13 @@ module Async
 			
 			return nil
 		end
+		
+		protected
+		
+		def exchange
+			waiting = @waiting
+			@waiting = List.new
+			return waiting
+		end
 	end
 end

data/lib/async/list.rb

@@ -0,0 +1,308 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2022, by Samuel Williams.
+
+module Async
+	# A general doublely linked list. This is used internally by {Async::Barrier} and {Async::Condition} to manage child tasks.
+	class List
+		# Initialize a new, empty, list.
+		def initialize
+			@head = self
+			@tail = self
+			@size = 0
+		end
+		
+		# Print a short summary of the list.
+		def to_s
+			sprintf("#<%s:0x%x size=%d>", self.class.name, object_id, @size)
+		end
+		
+		alias inspect to_s
+		
+		# Fast, safe, unbounded accumulation of children.
+		def to_a
+			items = []
+			current = self
+			
+			while current.tail != self
+				unless current.tail.is_a?(Iterator)
+					items << current.tail
+				end
+				
+				current = current.tail
+			end
+			
+			return items
+		end
+		
+		# Points at the end of the list.
+		attr_accessor :head
+		
+		# Points at the start of the list.
+		attr_accessor :tail
+		
+		attr :size
+		
+		# A callback that is invoked when an item is added to the list.
+		def added(node)
+			@size += 1
+			return node
+		end
+		
+		# Append a node to the end of the list.
+		def append(node)
+			if node.head
+				raise ArgumentError, "Node is already in a list!"
+			end
+			
+			node.tail = self
+			@head.tail = node
+			node.head = @head
+			@head = node
+			
+			return added(node)
+		end
+		
+		def prepend(node)
+			if node.head
+				raise ArgumentError, "Node is already in a list!"
+			end
+			
+			node.head = self
+			@tail.head = node
+			node.tail = @tail
+			@tail = node
+			
+			return added(node)
+		end
+		
+		# Add the node, yield, and the remove the node.
+		# @yields {|node| ...} Yields the node.
+		# @returns [Object] Returns the result of the block.
+		def stack(node, &block)
+			append(node)
+			return yield(node)
+		ensure
+			remove!(node)
+		end
+		
+		# A callback that is invoked when an item is removed from the list.
+		def removed(node)
+			@size -= 1
+			return node
+		end
+		
+		# Remove the node if it is in a list.
+		#
+		# You should be careful to only remove nodes that are part of this list.
+		#
+		# @returns [Node] Returns the node if it was removed, otherwise nil.
+		def remove?(node)
+			if node.head
+				return remove!(node)
+			end
+			
+			return nil
+		end
+		
+		# Remove the node. If it was already removed, this will raise an error.
+		#
+		# You should be careful to only remove nodes that are part of this list.
+		#
+		# @raises [ArgumentError] If the node is not part of this list.
+		# @returns [Node] Returns the node if it was removed, otherwise nil.
+		def remove(node)
+			# One downside of this interface is we don't actually check if the node is part of the list defined by `self`. This means that there is a potential for a node to be removed from a different list using this method, which in can throw off book-keeping when lists track size, etc.
+			unless node.head
+				raise ArgumentError, "Node is not in a list!"
+			end
+			
+			remove!(node)
+		end
+		
+		private def remove!(node)
+			node.head.tail = node.tail
+			node.tail.head = node.head
+			
+			# This marks the node as being removed, and causes remove to fail if called a 2nd time.
+			node.head = nil
+			# node.tail = nil
+			
+			return removed(node)
+		end
+		
+		# @returns [Boolean] Returns true if the list is empty.
+		def empty?
+			@size == 0
+		end
+		
+		# def validate!(node = nil)
+		# 	previous = self
+		# 	current = @tail
+		# 	found = node.equal?(self)
+			
+		# 	while true
+		# 		break if current.equal?(self)
+				
+		# 		if current.head != previous
+		# 			raise "Invalid previous linked list node!"
+		# 		end
+				
+		# 		if current.is_a?(List) and !current.equal?(self)
+		# 			raise "Invalid list in list node!"
+		# 		end
+				
+		# 		if node
+		# 			found ||= current.equal?(node)
+		# 		end
+				
+		# 		previous = current
+		# 		current = current.tail
+		# 	end
+			
+		# 	if node and !found
+		# 		raise "Node not found in list!"
+		# 	end
+		# end
+		
+		# Iterate over each node in the linked list. It is generally safe to remove the current node, any previous node or any future node during iteration.
+		#
+		# @yields {|node| ...} Yields each node in the list.
+		# @returns [List] Returns self.
+		def each(&block)
+			return to_enum unless block_given?
+			
+			Iterator.each(self, &block)
+			
+			return self
+		end
+		
+		# Determine whether the given node is included in the list. 
+		#
+		# @parameter needle [Node] The node to search for.
+		# @returns [Boolean] Returns true if the node is in the list.
+		def include?(needle)
+			self.each do |item|
+				return true if needle.equal?(item)
+			end
+			
+			return false
+		end
+		
+		# @returns [Node] Returns the first node in the list, if it is not empty.
+		def first
+			# validate!
+			
+			current = @tail
+			
+			while !current.equal?(self)
+				if current.is_a?(Iterator)
+					current = current.tail
+				else
+					return current
+				end
+			end
+			
+			return nil
+		end
+		
+		# @returns [Node] Returns the last node in the list, if it is not empty.
+		def last
+			# validate!
+			
+			current = @head
+			
+			while !current.equal?(self)
+				if current.is_a?(Iterator)
+					current = current.head
+				else
+					return current
+				end
+			end
+			
+			return nil
+		end
+		
+		def shift
+			if node = first
+				remove!(node)
+			end
+		end
+		
+		# A linked list Node.
+		class Node
+			attr_accessor :head
+			attr_accessor :tail
+			
+			alias inspect to_s
+		end
+		
+		class Iterator < Node
+			def initialize(list)
+				@list = list
+				
+				# Insert the iterator as the first item in the list:
+				@tail = list.tail
+				@tail.head = self
+				list.tail = self
+				@head = list
+			end
+			
+			def remove!
+				@head.tail = @tail
+				@tail.head = @head
+				@head = nil
+				@tail = nil
+				@list = nil
+			end
+			
+			def move_next
+				# Move to the next item (which could be an iterator or the end):
+				@tail.head = @head
+				@head.tail = @tail
+				@head = @tail
+				@tail = @tail.tail
+				@head.tail = self
+				@tail.head = self
+			end
+			
+			def move_current
+				while true
+					# Are we at the end of the list?
+					if @tail.equal?(@list)
+						return nil
+					end
+					
+					if @tail.is_a?(Iterator)
+						move_next
+					else
+						return @tail
+					end
+				end
+			end
+			
+			def each
+				while current = move_current
+					yield current
+					
+					if current.equal?(@tail)
+						move_next
+					end
+				end
+			end
+			
+			def self.each(list, &block)
+				return if list.empty?
+				
+				iterator = Iterator.new(list)
+				
+				iterator.each(&block)
+			ensure
+				iterator&.remove!
+			end
+		end
+		
+		private_constant :Iterator
+	end
+end

data/lib/async/node.rb

@@ -5,138 +5,48 @@
 # Copyright, 2017, by Kent Gruber.
 # Copyright, 2022, by Shannon Skipper.
 
+require_relative 'list'
+
 module Async
-	# A double linked list used for managing tasks.
-	class List
-		def initialize
-			# The list behaves like a list node, so @tail points to the next item (the first one) and head points to the previous item (the last one). This may be slightly confusing but it makes the interface more natural.
-			@head = nil
-			@tail = nil
-			@size = 0
-		end
-		
-		attr :size
-		
-		attr_accessor :head
-		attr_accessor :tail
-		
-		# Inserts an item at the end of the list.
-		def insert(item)
-			unless @tail
-				@tail = item
-				@head = item
-				
-				# Consistency:
-				item.head = nil
-				item.tail = nil
-			else
-				@head.tail = item
-				item.head = @head
-				
-				# Consistency:
-				item.tail = nil
-				
-				@head = item
-			end
-			
-			@size += 1
-			
-			return self
-		end
-		
-		def delete(item)
-			if @tail.equal?(item)
-				@tail = @tail.tail
-			else
-				item.head.tail = item.tail
-			end
-			
-			if @head.equal?(item)
-				@head = @head.head
-			else
-				item.tail.head = item.head
-			end
-			
-			item.head = nil
-			item.tail = nil
-			
-			@size -= 1
-			
-			return self
-		end
-		
-		def each(&block)
-			return to_enum unless block_given?
-			
-			current = self
-			while node = current.tail
-				yield node
-				
-				# If the node has deleted itself or any subsequent node, it will no longer be the next node, so don't use it for continued traversal:
-				if current.tail.equal?(node)
-					current = node
-				end
-			end
-		end
-		
-		def include?(needle)
-			self.each do |item|
-				return true if needle.equal?(item)
-			end
-			
-			return false
-		end
-		
-		def first
-			@tail
-		end
-		
-		def last
-			@head
-		end
-		
-		def empty?
-			@tail.nil?
-		end
-		
-		def nil?
-			@tail.nil?
-		end
-	end
-	
-	private_constant :List
-	
 	# A list of children tasks.
 	class Children < List
 		def initialize
 			super
-			
 			@transient_count = 0
 		end
 		
-		# Does this node have (direct) transient children?
+		# Some children may be marked as transient. Transient children do not prevent the parent from finishing.
+		# @returns [Boolean] Whether the node has transient children.
 		def transients?
 			@transient_count > 0
 		end
 		
-		def insert(item)
-			if item.transient?
+		# Whether all children are considered finished. Ignores transient children.
+		def finished?
+			@size == @transient_count
+		end
+		
+		# Whether the children is empty, preserved for compatibility.
+		def nil?
+			empty?
+		end
+		
+		private
+		
+		def added(node)
+			if node.transient?
 				@transient_count += 1
 			end
 			
-			super
+			return super
 		end
 		
-		def delete(item)
-			if item.transient?
+		def removed(node)
+			if node.transient?
 				@transient_count -= 1
 			end
 			
-			super
-		end
-		
-		def finished?
-			@size == @transient_count
+			return super
 		end
 	end
 	
@@ -181,12 +91,18 @@ module Async
 		# A useful identifier for the current node.
 		attr :annotation
 		
-		# Whether there are children?
+		# Whether this node has any children.
+		# @returns [Boolean]
 		def children?
-			@children != nil && !@children.empty?
+			@children && !@children.empty?
 		end
 		
-		# Is this node transient?
+		# Represents whether a node is transient. Transient nodes are not considered
+		# when determining if a node is finished. This is useful for tasks which are
+		# internal to an object rather than explicit user concurrency. For example,
+		# a child task which is pruning a connection pool is transient, because it
+		# is not directly related to the parent task, and should not prevent the
+		# parent task from finishing.
 		def transient?
 			@transient
 		end
@@ -225,13 +141,14 @@ module Async
 		alias inspect to_s
 		
 		# Change the parent of this node.
-		# @parameter parent [Node | Nil] the parent to attach to, or nil to detach.
+		#
+		# @parameter parent [Node | Nil] The parent to attach to, or nil to detach.
 		# @returns [Node] Itself.
 		def parent=(parent)
 			return if @parent.equal?(parent)
 			
 			if @parent
-				@parent.delete_child(self)
+				@parent.remove_child(self)
 				@parent = nil
 			end
 			
@@ -242,23 +159,23 @@ module Async
 			return self
 		end
 		
-		protected def set_parent parent
+		protected def set_parent(parent)
 			@parent = parent
 		end
 		
-		protected def add_child child
+		protected def add_child(child)
 			@children ||= Children.new
-			@children.insert(child)
+			@children.append(child)
 			child.set_parent(self)
 		end
 		
-		protected def delete_child(child)
-			@children.delete(child)
+		protected def remove_child(child)
+			@children.remove(child)
 			child.set_parent(nil)
 		end
 		
-		# Whether the node can be consumed safely. By default, checks if the
-		# children set is empty.
+		# Whether the node can be consumed (deleted) safely. By default, checks if the children set is empty.
+		#
 		# @returns [Boolean]
 		def finished?
 			@children.nil? || @children.finished?
@@ -268,15 +185,14 @@ module Async
 		# the parent.
 		def consume
 			if parent = @parent and finished?
-				parent.delete_child(self)
+				parent.remove_child(self)
 				
+				# If we have children, then we need to move them to our the parent if they are not finished:
 				if @children
-					@children.each do |child|
+					while child = @children.shift
 						if child.finished?
-							delete_child(child)
+							child.set_parent(nil)
 						else
-							# In theory we don't need to do this... because we are throwing away the list. However, if you don't correctly update the list when moving the child to the parent, it foobars the enumeration, and subsequent nodes will be skipped, or in the worst case you might start enumerating the parents nodes.
-							delete_child(child)
 							parent.add_child(child)
 						end
 					end
@@ -288,18 +204,25 @@ module Async
 			end
 		end
 		
-		# Traverse the tree.
+		# Traverse the task tree.
+		#
+		# @returns [Enumerator] An enumerator which will traverse the tree if no block is given.
 		# @yields {|node, level| ...} The node and the level relative to the given root.
-		def traverse(level = 0, &block)
+		def traverse(&block)
+			return enum_for(:traverse) unless block_given?
+			
+			self.traverse_recurse(&block)
+		end
+		
+		protected def traverse_recurse(level = 0, &block)
 			yield self, level
 			
 			@children&.each do |child|
-				child.traverse(level + 1, &block)
+				child.traverse_recurse(level + 1, &block)
 			end
 		end
 		
-		# Immediately terminate all children tasks, including transient tasks.
-		# Internally invokes `stop(false)` on all children.
+		# Immediately terminate all children tasks, including transient tasks. Internally invokes `stop(false)` on all children. This should be considered a last ditch effort and is used when closing the scheduler.
 		def terminate
 			# Attempt to stop the current task immediately, and all children:
 			stop(false)
@@ -310,8 +233,8 @@ module Async
 			end
 		end
 		
-		# Attempt to stop the current node immediately, including all non-transient children.
-		# Invokes {#stop_children} to stop all children.
+		# Attempt to stop the current node immediately, including all non-transient children. Invokes {#stop_children} to stop all children.
+		#
 		# @parameter later [Boolean] Whether to defer stopping until some point in the future.
 		def stop(later = false)
 			# The implementation of this method may defer calling `stop_children`.

data/lib/async/notification.rb

@@ -13,9 +13,7 @@ module Async
 		def signal(value = nil, task: Task.current)
 			return if @waiting.empty?
 			
-			Fiber.scheduler.push Signal.new(@waiting, value)
-			
-			@waiting = []
+			Fiber.scheduler.push Signal.new(self.exchange, value)
 			
 			return nil
 		end

data/lib/async/reactor.rb

@@ -21,6 +21,10 @@ module Async
 			Fiber.set_scheduler(self)
 		end
 		
+		def scheduler_close
+			self.close
+		end
+		
 		public :sleep
 	end
 end

data/lib/async/scheduler.rb

@@ -34,6 +34,12 @@ module Async
 			@timers = ::Timers::Group.new
 		end
 		
+		def scheduler_close
+			self.run
+		ensure
+			self.close
+		end
+		
 		# @public Since `stable-v1`.
 		def close
 			# This is a critical step. Because tasks could be stored as instance variables, and since the reactor is (probably) going out of scope, we need to ensure they are stopped. Otherwise, the tasks will belong to a reactor that will never run again and are not stopped.

data/lib/async/semaphore.rb

@@ -3,6 +3,8 @@
 # Released under the MIT License.
 # Copyright, 2018-2022, by Samuel Williams.
 
+require_relative 'list'
+
 module Async
 	# A synchronization primitive, which limits access to a given resource.
 	# @public Since `stable-v1`.
@@ -12,7 +14,7 @@ module Async
 		def initialize(limit = 1, parent: nil)
 			@count = 0
 			@limit = limit
-			@waiting = []
+			@waiting = List.new
 			
 			@parent = parent
 		end
@@ -73,26 +75,34 @@ module Async
 		def release
 			@count -= 1
 			
-			while (@limit - @count) > 0 and fiber = @waiting.shift
-				if fiber.alive?
-					Fiber.scheduler.resume(fiber)
-				end
+			while (@limit - @count) > 0 and node = @waiting.first
+				node.resume
 			end
 		end
 		
 		private
 		
+		class FiberNode < List::Node
+			def initialize(fiber)
+				@fiber = fiber
+			end
+			
+			def resume
+				if @fiber.alive?
+					Fiber.scheduler.resume(@fiber)
+				end
+			end
+		end
+		
+		private_constant :FiberNode
+		
 		# Wait until the semaphore becomes available.
 		def wait
-			fiber = Fiber.current
+			return unless blocking?
 			
-			if blocking?
-				@waiting << fiber
+			@waiting.stack(FiberNode.new(Fiber.current)) do
 				Fiber.scheduler.transfer while blocking?
 			end
-		rescue Exception
-			@waiting.delete(fiber)
-			raise
 		end
 	end
 end

data/lib/async/task.rb

@@ -111,7 +111,10 @@ module Async
 			end
 		end
 		
+		# Run an asynchronous task as a child of the current task.
 		def async(*arguments, **options, &block)
+			raise "Cannot create child task within a task that has finished execution!" if self.finished?
+			
 			task = Task.new(self, **options, &block)
 			
 			task.run(*arguments)
@@ -119,26 +122,28 @@ module Async
 			return task
 		end
 		
-		# Retrieve the current result of the task. Will cause the caller to wait until result is available.
-		# @raises[RuntimeError] If the task's fiber is the current fiber.
+		# Retrieve the current result of the task. Will cause the caller to wait until result is available. If the result was an exception, raise that exception.
+		#
+		# Conceptually speaking, waiting on a task should return a result, and if it throws an exception, this is certainly an exceptional case that should represent a failure in your program, not an expected outcome. In other words, you should not design your programs to expect exceptions from `#wait` as a normal flow control, and prefer to catch known exceptions within the task itself and return a result that captures the intention of the failure, e.g. a `TimeoutError` might simply return `nil` or `false` to indicate that the operation did not generate a valid result (as a timeout was an expected outcome of the internal operation in this case).
+		#
+		# @raises [RuntimeError] If the task's fiber is the current fiber.
 		# @returns [Object] The final expression/result of the task's block.
 		def wait
-			raise "Cannot wait on own fiber" if Fiber.current.equal?(@fiber)
+			raise "Cannot wait on own fiber!" if Fiber.current.equal?(@fiber)
 			
 			if running?
 				@finished ||= Condition.new
 				@finished.wait
 			end
 			
-			case @result
-			when Exception
+			if @result.is_a?(Exception)
 				raise @result
 			else
 				return @result
 			end
 		end
 		
-		# Access the result of the task without waiting. May be nil if the task is not completed.
+		# Access the result of the task without waiting. May be nil if the task is not completed. Does not raise exceptions.
 		attr :result
 		
 		# Stop the task and all of its children.
@@ -258,7 +263,7 @@ module Async
 			self.root.resume(@fiber)
 		end
 		
-		# Finish the current task, and all bound bound IO objects.
+		# Finish the current task, moving any children to the parent.
 		def finish!
 			# Allow the fiber to be recycled.
 			@fiber = nil
@@ -268,7 +273,7 @@ module Async
 			
 			# If this task was being used as a future, signal completion here:
 			if @finished
-				@finished.signal(@result)
+				@finished.signal(self)
 			end
 		end
 		

data/lib/async/version.rb

@@ -4,5 +4,5 @@
 # Copyright, 2017-2022, by Samuel Williams.
 
 module Async
-	VERSION = "2.2.1"
+	VERSION = "2.3.1"
 end

data/lib/async/waiter.md

@@ -0,0 +1,50 @@
+A synchronization primitive, which allows you to wait for tasks to complete in order of completion. This is useful for implementing a task pool, where you want to wait for the first task to complete, and then cancel the rest.
+
+If you try to wait for more things than you have added, you will deadlock.
+
+## Example
+
+~~~ ruby
+require 'async'
+require 'async/semaphore'
+require 'async/barrier'
+require 'async/waiter'
+
+Sync do
+	barrier = Async::Barrier.new
+	waiter = Async::Waiter.new(parent: barrier)
+	semaphore = Async::Semaphore.new(2, parent: waiter)
+	
+	# Sleep sort the numbers:
+	generator = Async do
+		while true
+			semaphore.async do |task|
+				number = rand(1..10)
+				sleep(number)
+			end
+		end
+	end
+	
+	numbers = []
+	
+	4.times do
+		# Wait for all the numbers to be sorted:
+		numbers << waiter.wait
+	end
+	
+	# Don't generate any more numbers:
+	generator.stop
+	
+	# Stop all tasks which we don't care about:
+	barrier.stop
+	
+	Console.logger.info("Smallest", numbers)
+end
+~~~
+
+### Output
+
+~~~
+0.0s     info: Smallest
+             | [3, 3, 1, 2]
+~~~

data/lib/async/waiter.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2022, by Samuel Williams.
+
+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
+		def initialize(parent: nil, finished: Async::Condition.new)
+			@finished = finished
+			@done = []
+			
+			@parent = parent
+		end
+		
+		# 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|
+				yield(task)
+			ensure
+				@done << task
+				@finished.signal
+			end
+		end
+		
+		# Wait for the first `count` tasks to complete.
+		# @parameter count [Integer | Nil] The number of tasks to wait for.
+		# @returns [Array(Async::Task)] If an integer is given, the tasks which have completed.
+		# @returns [Async::Task] Otherwise, the first task to complete.
+		def first(count = nil)
+			minimum = count || 1
+			
+			while @done.size < minimum
+				@finished.wait
+			end
+			
+			return @done.shift(*count)
+		end
+		
+		# Wait for the first `count` tasks to complete.
+		# @parameter count [Integer | Nil] The number of tasks to wait for.
+		def wait(count = nil)
+			if count
+				first(count).map(&:wait)
+			else
+				first.wait
+			end
+		end
+	end
+end

data/lib/kernel/async.rb

@@ -25,6 +25,7 @@ module Kernel
 		if current = ::Async::Task.current?
 			return current.async(...)
 		else
+			# This calls Fiber.set_scheduler(self):
 			reactor = ::Async::Reactor.new
 			
 			begin

data/lib/kernel/sync.rb

@@ -19,6 +19,7 @@ module Kernel
 		if task = ::Async::Task.current?
 			yield task
 		else
+			# This calls Fiber.set_scheduler(self):
 			reactor = Async::Reactor.new
 			
 			begin

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async
 version: !ruby/object:Gem::Version
-  version: 2.2.1
+  version: 2.3.1
 platform: ruby
 authors:
 - Samuel Williams
@@ -54,7 +54,7 @@ cert_chain:
   Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
   voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
   -----END CERTIFICATE-----
-date: 2022-10-13 00:00:00.000000000 Z
+date: 2022-12-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: console
@@ -76,14 +76,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.1.0
+        version: '1.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.1.0
+        version: '1.1'
 - !ruby/object:Gem::Dependency
   name: timers
   requirement: !ruby/object:Gem::Requirement
@@ -174,28 +174,42 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.10'
+        version: 0.18.3
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.10'
+        version: 0.18.3
 - !ruby/object:Gem::Dependency
-  name: rspec
+  name: sus
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.6'
+        version: '0.15'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.6'
+        version: '0.15'
+- !ruby/object:Gem::Dependency
+  name: sus-fixtures-async
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description:
 email:
 executables: []
@@ -208,6 +222,7 @@ files:
 - lib/async/clock.rb
 - lib/async/condition.md
 - lib/async/condition.rb
+- lib/async/list.rb
 - lib/async/node.rb
 - lib/async/notification.rb
 - lib/async/queue.rb
@@ -218,6 +233,8 @@ files:
 - lib/async/task.rb
 - lib/async/variable.rb
 - lib/async/version.rb
+- lib/async/waiter.md
+- lib/async/waiter.rb
 - lib/async/wrapper.rb
 - lib/kernel/async.rb
 - lib/kernel/sync.rb
@@ -242,7 +259,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.7
+rubygems_version: 3.4.1
 signing_key:
 specification_version: 4
 summary: A concurrency framework for Ruby.