async 2.12.1 → 2.14.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1eef4bf800b6d52c0f273289186f9886975237ecdf9885f599617691283ca2e5
-  data.tar.gz: 14a7e20dc72c178b89a93233a73fd49f182f7aec7926804b9b8bf37e8ceb9f36
+  metadata.gz: ffbf235f3425b766c8eedfcdb2b03f86569e43ab1cdda3bd44f74c1b25f516b7
+  data.tar.gz: 1d71883b2151b5eb0f23daf27221ac091d352809a0ef1f687f282696cd22ae79
 SHA512:
-  metadata.gz: 30176358a5c9efc3df3e525e0ba941f5771bb7619bef28e1b6229a547ad3a24cb5475483a257704c3eea2d9214dcca2e17932994e0859a1c5d4dfc6401b24d48
-  data.tar.gz: 8b7353cf2ef0884c78a919775b84280d3234c7868c6c3b95aa00ae560a5825a07bd9533eda1afcc9776d1c94b7cc116e549e24144e4bab7c9bb3f086782a7456
+  metadata.gz: a00499f9ea43ffee3e6a5cf65dee14f67c5dcd167cb68e1b5da7c11bcef51c06da9c8c2d7a0606f72e5802520f7b9837f128d8425ade3de75111ca16a4cc9c10
+  data.tar.gz: f65b60522c85e07a17fdc345944c06e7447095682afea0bd2b7dcbf462deeeb7dcb6053e82eefc96cc259b10d6b0849803b8f22356feb10a21666a5ab134f6d6

data/lib/async/condition.rb

@@ -11,6 +11,7 @@ module Async
 	# A synchronization primitive, which allows fibers to wait until a particular condition is (edge) triggered.
 	# @public Since `stable-v1`.
 	class Condition
+		# Create a new condition.
 		def initialize
 			@waiting = List.new
 		end
@@ -39,12 +40,16 @@ module Async
 			end
 		end
 		
-		# Is any fiber waiting on this notification?
-		# @returns [Boolean]
+		# @deprecated Replaced by {#waiting?}
 		def empty?
 			@waiting.empty?
 		end
 		
+		# @returns [Boolean] Is any fiber waiting on this notification?
+		def waiting?
+			@waiting.size > 0
+		end
+		
 		# 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)

data/lib/async/idler.rb

@@ -4,13 +4,28 @@
 # Copyright, 2024, by Samuel Williams.
 
 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`.
+		#
+		# @parameter maximum_load [Numeric] The maximum load before we start shedding work.
+		# @parameter backoff [Numeric] The initial backoff time, used for delaying work.
+		# @parameter parent [Interface(:async) | Nil] The parent task to use for async operations.
 		def initialize(maximum_load = 0.8, backoff: 0.01, parent: nil)
 			@maximum_load = maximum_load
 			@backoff = backoff
 			@parent = parent
 		end
 		
+		# Wait until the system is idle, then execute the given block in a new task.
+		#
+		# @asynchronous Executes the given block concurrently.
+		#
+		# @parameter arguments [Array] The arguments to pass to the block.
+		# @parameter parent [Interface(:async) | Nil] The parent task to use for async operations.
+		# @parameter options [Hash] The options to pass to the task.
+		# @yields {|task| ...} When the system is idle, the block will be executed in a new task.
 		def async(*arguments, parent: (@parent or Task.current), **options, &block)
 			wait
 			
@@ -18,6 +33,9 @@ module Async
 			parent.async(*arguments, **options, &block)
 		end
 		
+		# Wait until the system is idle, according to the maximum load specified.
+		#
+		# If the scheduler is overloaded, this method will sleep for an exponentially increasing amount of time.
 		def wait
 			scheduler = Fiber.scheduler
 			backoff = nil

data/lib/async/list.rb

@@ -13,7 +13,7 @@ module Async
 			@size = 0
 		end
 		
-		# Print a short summary of the list.
+		# @returns [String] A short summary of the list.
 		def to_s
 			sprintf("#<%s:0x%x size=%d>", self.class.name, object_id, @size)
 		end
@@ -36,12 +36,13 @@ module Async
 			return items
 		end
 		
-		# Points at the end of the list.
+		# @attribute [Node | Nil] Points at the end of the list.
 		attr_accessor :head
 		
-		# Points at the start of the list.
+		# @attribute [Node | Nil] Points at the start of the list.
 		attr_accessor :tail
 		
+		# @attribute [Integer] The number of nodes in the list.
 		attr :size
 		
 		# A callback that is invoked when an item is added to the list.
@@ -64,6 +65,7 @@ module Async
 			return added(node)
 		end
 		
+		# Prepend a node to the start of the list.
 		def prepend(node)
 			if node.head
 				raise ArgumentError, "Node is already in a list!"
@@ -224,6 +226,7 @@ module Async
 			return nil
 		end
 		
+		# Shift the first node off the list, if it is not empty.
 		def shift
 			if node = first
 				remove!(node)

data/lib/async/node.rb

@@ -12,6 +12,7 @@ require_relative 'list'
 module Async
 	# A list of children tasks.
 	class Children < List
+		# Create an empty list of children tasks.
 		def initialize
 			super
 			@transient_count = 0
@@ -73,7 +74,7 @@ module Async
 			end
 		end
 		
-		# @returns [Node] the root node in the hierarchy.
+		# @returns [Node] The root node in the hierarchy.
 		def root
 			@parent&.root || self
 		end
@@ -87,10 +88,10 @@ module Async
 		# @attribute [Node] The parent node.
 		attr :parent
 		
-		# @attribute children [Children | Nil] Optional list of children.
+		# @attribute [Children | Nil] Optional list of children.
 		attr :children
 		
-		# A useful identifier for the current node.
+		# @attribute [String | Nil] A useful identifier for the current node.
 		attr :annotation
 		
 		# Whether this node has any children.
@@ -109,6 +110,9 @@ module Async
 			@transient
 		end
 		
+		# Annotate the node with a description.
+		#
+		# @parameter annotation [String] The description to annotate the node with.
 		def annotate(annotation)
 			if block_given?
 				begin
@@ -123,6 +127,9 @@ module Async
 			end
 		end
 		
+		# A description of the node, including the annotation and object name.
+		#
+		# @returns [String] The description of the node.
 		def description
 			@object_name ||= "#{self.class}:#{format '%#018x', object_id}#{@transient ? ' transient' : nil}"
 			
@@ -135,10 +142,14 @@ module Async
 			end
 		end
 		
+		# Provides a backtrace for nodes that have an active execution context.
+		#
+		# @returns [Array(Thread::Backtrace::Locations) | Nil] The backtrace of the node, if available.
 		def backtrace(*arguments)
 			nil
 		end
 		
+		# @returns [String] A description of the node.
 		def to_s
 			"\#<#{self.description}>"
 		end
@@ -255,10 +266,15 @@ module Async
 			end
 		end
 		
+		# Whether the node has been stopped.
 		def stopped?
 			@children.nil?
 		end
 		
+		# Print the hierarchy of the task tree from the given node.
+		#
+		# @parameter out [IO] The output stream to write to.
+		# @parameter backtrace [Boolean] Whether to print the backtrace of each node.
 		def print_hierarchy(out = $stdout, backtrace: true)
 			self.traverse do |node, level|
 				indent = "\t" * level

data/lib/async/notification.rb

@@ -29,5 +29,7 @@ module Async
 				end
 			end
 		end
+		
+		private_constant :Signal
 	end
 end

data/lib/async/queue.rb

@@ -9,68 +9,104 @@ require_relative 'notification'
 
 module Async
 	# A queue which allows items to be processed in order.
+	#
+	# It has a compatible interface with {Notification} and {Condition}, except that it's multi-value.
+	#
 	# @public Since `stable-v1`.
-	class Queue < Notification
-		def initialize(parent: nil)
-			super()
-			
+	class Queue
+		# Create a new queue.
+		#
+		# @parameter parent [Interface(:async) | Nil] The parent task to use for async operations.
+		# @parameter available [Notification] The notification to use for signaling when items are available.
+		def initialize(parent: nil, available: Notification.new)
 			@items = []
 			@parent = parent
+			@available = available
 		end
 		
+		# @attribute [Array] The items in the queue.
 		attr :items
 		
+		# @returns [Integer] The number of items in the queue.
 		def size
 			@items.size
 		end
-
+		
+		# @returns [Boolean] Whether the queue is empty.
 		def empty?
 			@items.empty?
 		end
 		
+		# Add an item to the queue.
 		def <<(item)
 			@items << item
 			
-			self.signal unless self.empty?
+			@available.signal unless self.empty?
 		end
 		
+		# Add multiple items to the queue.
 		def enqueue(*items)
 			@items.concat(items)
 			
-			self.signal unless self.empty?
+			@available.signal unless self.empty?
 		end
 		
+		# Remove and return the next item from the queue.
 		def dequeue
 			while @items.empty?
-				self.wait
+				@available.wait
 			end
 			
 			@items.shift
 		end
 		
-		def async(parent: (@parent or Task.current), &block)
+		# Process each item in the queue.
+		#
+		# @asynchronous Executes the given block concurrently for each item.
+		#
+		# @parameter arguments [Array] The arguments to pass to the block.
+		# @parameter parent [Interface(:async) | Nil] The parent task to use for async operations.
+		# @parameter options [Hash] The options to pass to the task.
+		# @yields {|task| ...} When the system is idle, the block will be executed in a new task.
+		def async(parent: (@parent or Task.current), **options, &block)
 			while item = self.dequeue
-				parent.async(item, &block)
+				parent.async(item, **options, &block)
 			end
 		end
 		
+		# Enumerate each item in the queue.
 		def each
 			while item = self.dequeue
 				yield item
 			end
 		end
+		
+		# Signal the queue with a value, the same as {#enqueue}.
+		def signal(value)
+			self.enqueue(value)
+		end
+		
+		# Wait for an item to be available, the same as {#dequeue}.
+		def wait
+			self.dequeue
+		end
 	end
 	
+	# A queue which limits the number of items that can be enqueued.
 	# @public Since `stable-v1`.
 	class LimitedQueue < Queue
-		def initialize(limit = 1, **options)
+		# Create a new limited queue.
+		#
+		# @parameter limit [Integer] The maximum number of items that can be enqueued.
+		# @parameter full [Notification] The notification to use for signaling when the queue is full.
+		def initialize(limit = 1, full: Notification.new, **options)
 			super(**options)
 			
 			@limit = limit
-			
-			@full = Notification.new
+			@full = full
 		end
 		
+		# @attribute [Integer] The maximum number of items that can be enqueued.
 		attr :limit
 		
 		# @returns [Boolean] Whether trying to enqueue an item would block.
@@ -78,6 +114,11 @@ module Async
 			@items.size >= @limit
 		end
 		
+		# Add an item to the queue.
+		#
+		# If the queue is full, this method will block until there is space available.
+		#
+		# @parameter item [Object] The item to add to the queue.
 		def <<(item)
 			while limited?
 				@full.wait
@@ -86,7 +127,12 @@ module Async
 			super
 		end
 		
-		def enqueue *items
+		# Add multiple items to the queue.
+		#
+		# If the queue is full, this method will block until there is space available. 
+		#
+		# @parameter items [Array] The items to add to the queue.
+		def enqueue(*items)
 			while !items.empty?
 				while limited?
 					@full.wait
@@ -95,10 +141,15 @@ module Async
 				available = @limit - @items.size
 				@items.concat(items.shift(available))
 				
-				self.signal unless self.empty?
+				@available.signal unless self.empty?
 			end
 		end
 		
+		# Remove and return the next item from the queue.
+		#
+		# If the queue is empty, this method will block until an item is available.
+		#
+		# @returns [Object] The next item in the queue.
 		def dequeue
 			item = super
 			

data/lib/async/reactor.rb

@@ -15,12 +15,14 @@ module Async
 			Async(...)
 		end
 		
+		# Initialize the reactor and assign it to the current Fiber scheduler.
 		def initialize(...)
 			super
 			
 			Fiber.set_scheduler(self)
 		end
 		
+		# Close the reactor and remove it from the current Fiber scheduler.
 		def scheduler_close
 			self.close
 		end

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)
 			
@@ -63,6 +72,9 @@ module Async
 			end
 		end
 		
+		# Invoked when the fiber scheduler is being closed.
+		#
+		# Executes the run loop until all tasks are finished, then closes the scheduler.
 		def scheduler_close
 			# If the execution context (thread) was handling an exception, we want to exit as quickly as possible:
 			unless $!
@@ -79,6 +91,7 @@ module Async
 			end
 		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.
@@ -108,6 +121,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 +149,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

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
@@ -72,14 +87,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 +110,7 @@ module Async
 			end
 		end
 		
+		# @returns [Object] The annotation of the task.
 		def annotation
 			if @fiber
 				@fiber.annotation
@@ -96,6 +119,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 +139,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 +154,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 fiber, 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("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 +204,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?
 			
@@ -289,15 +327,16 @@ module Async
 		# @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 +365,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 +399,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

@@ -6,12 +6,21 @@
 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,15 +31,22 @@ module Async
 			condition.signal(value)
 		end
 		
+		# Whether the value has been resolved.
+		#
+		# @returns [Boolean] Whether the value has been resolved.
 		def resolved?
 			@condition.nil?
 		end
 		
+		# Wait for the value to be resolved.
+		#
+		# @returns [Object] The resolved value.
 		def value
 			@condition&.wait
 			return @value
 		end
 		
+		# Alias for {#value}.
 		def wait
 			self.value
 		end

data/lib/async/version.rb

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

data/lib/async/waiter.rb

@@ -6,6 +6,10 @@
 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 +19,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

data/lib/async/wrapper.rb

@@ -23,6 +23,7 @@ module Async
 		
 		attr_accessor :reactor
 		
+		# Dup the underlying IO.
 		def dup
 			self.class.new(@io.dup)
 		end
@@ -51,11 +52,12 @@ module Async
 			@io.to_io.wait(::IO::READABLE|::IO::WRITABLE|::IO::PRIORITY, timeout) or raise TimeoutError
 		end
 		
-		# Close the io and monitor.
+		# Close the underlying IO.
 		def close
 			@io.close
 		end
 		
+		# Whether the underlying IO is closed.
 		def closed?
 			@io.closed?
 		end

data/lib/async.rb

@@ -10,5 +10,6 @@ require_relative "async/reactor"
 require_relative "kernel/async"
 require_relative "kernel/sync"
 
+# Asynchronous programming framework.
 module Async
 end

data/readme.md

@@ -1,4 +1,4 @@
-# ![Async](logo.svg)
+# ![Async](assets/logo.webp)
 
 Async is a composable asynchronous I/O framework for Ruby based on [io-event](https://github.com/socketry/io-event).
 
@@ -19,20 +19,17 @@ Async is a composable asynchronous I/O framework for Ruby based on [io-event](ht
 
 Please see the [project documentation](https://socketry.github.io/async/) for more details.
 
-  - [Getting Started](https://socketry.github.io/async/guides/getting-started/index) - This guide shows how to add
-    async to your project and run code asynchronously.
+  - [Getting Started](https://socketry.github.io/async/guides/getting-started/index) - This guide shows how to add async to your project and run code asynchronously.
 
-  - [Asynchronous Tasks](https://socketry.github.io/async/guides/asynchronous-tasks/index) - This guide explains how
-    asynchronous tasks work and how to use them.
+  - [Asynchronous Tasks](https://socketry.github.io/async/guides/asynchronous-tasks/index) - This guide explains how asynchronous tasks work and how to use them.
 
-  - [Event Loop](https://socketry.github.io/async/guides/event-loop/index) - This guide gives an overview of how the
-    event loop is implemented.
+  - [Event Loop](https://socketry.github.io/async/guides/event-loop/index) - This guide gives an overview of how the event loop is implemented.
 
-  - [Compatibility](https://socketry.github.io/async/guides/compatibility/index) - This guide gives an overview of the
-    compatibility of Async with Ruby and other frameworks.
+  - [Compatibility](https://socketry.github.io/async/guides/compatibility/index) - This guide gives an overview of the compatibility of Async with Ruby and other frameworks.
 
-  - [Best Practices](https://socketry.github.io/async/guides/best-practices/index) - This guide gives an overview of
-    best practices for using Async.
+  - [Best Practices](https://socketry.github.io/async/guides/best-practices/index) - This guide gives an overview of best practices for using Async.
+
+  - [Debugging](https://socketry.github.io/async/guides/debugging/index) - This guide explains how to debug issues with programs that use Async.
 
 ## Contributing
 
@@ -54,16 +51,9 @@ This project is governed by the [Contributor Covenant](https://www.contributor-c
 
 ## See Also
 
-  - [async-io](https://github.com/socketry/async-io) — Asynchronous networking and sockets.
   - [async-http](https://github.com/socketry/async-http) — Asynchronous HTTP client/server.
-  - [async-process](https://github.com/socketry/async-process) — Asynchronous process spawning/waiting.
   - [async-websocket](https://github.com/socketry/async-websocket) — Asynchronous client and server websockets.
   - [async-dns](https://github.com/socketry/async-dns) — Asynchronous DNS resolver and server.
-  - [async-rspec](https://github.com/socketry/async-rspec) — Shared contexts for running async specs.
-
-### Projects Using Async
-
-  - [ciri](https://github.com/ciri-ethereum/ciri) — An Ethereum implementation written in Ruby.
   - [falcon](https://github.com/socketry/falcon) — A rack compatible server built on top of `async-http`.
   - [rubydns](https://github.com/ioquatix/rubydns) — An easy to use Ruby DNS server.
   - [slack-ruby-bot](https://github.com/slack-ruby/slack-ruby-bot) — A client for making slack bots.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async
 version: !ruby/object:Gem::Version
-  version: 2.12.1
+  version: 2.14.1
 platform: ruby
 authors:
 - Samuel Williams
@@ -62,7 +62,7 @@ cert_chain:
   Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
   voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
   -----END CERTIFICATE-----
-date: 2024-06-23 00:00:00.000000000 Z
+date: 2024-07-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: console