async 2.12.1 → 2.16.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1eef4bf800b6d52c0f273289186f9886975237ecdf9885f599617691283ca2e5
-  data.tar.gz: 14a7e20dc72c178b89a93233a73fd49f182f7aec7926804b9b8bf37e8ceb9f36
+  metadata.gz: cd3699fb686c1acc86c39923b81f946f30be577b19eedde83ccb18c156490bfa
+  data.tar.gz: 27f7af6e0106d94fc8d0a6da188d6c923bc9afce09a32fddad1258367f9d683c
 SHA512:
-  metadata.gz: 30176358a5c9efc3df3e525e0ba941f5771bb7619bef28e1b6229a547ad3a24cb5475483a257704c3eea2d9214dcca2e17932994e0859a1c5d4dfc6401b24d48
-  data.tar.gz: 8b7353cf2ef0884c78a919775b84280d3234c7868c6c3b95aa00ae560a5825a07bd9533eda1afcc9776d1c94b7cc116e549e24144e4bab7c9bb3f086782a7456
+  metadata.gz: 3e3d03ffcf1b3f7f3d3a4d8f3285092e4a6a6367f91259fbc17aba628d2aa6c8dbbbdcae0093a129a4a7f942f9bcf805d29cfe4e0cd715627ec62098a0e91303
+  data.tar.gz: 65c681adf6715d125e270b323a39db62cf91efd22628884f48131b68f639ffdd5acc69402181b33f63104a2fb648135f327b2abce8a39d366024be0ca7c30665

data/lib/async/condition.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2017-2022, by Samuel Williams.
+# Copyright, 2017-2024, by Samuel Williams.
 # Copyright, 2017, by Kent Gruber.
 
 require 'fiber'
@@ -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,12 +33,16 @@ 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
 			
 			while true
-				load = scheduler.load 
+				load = scheduler.load
+				
 				break if load < @maximum_load
 				
 				if backoff

data/lib/async/list.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2022, by Samuel Williams.
+# Copyright, 2022-2024, by Samuel Williams.
 
 module Async
 	# A general doublely linked list. This is used internally by {Async::Barrier} and {Async::Condition} to manage child tasks.
@@ -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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2017-2023, by Samuel Williams.
+# Copyright, 2017-2024, by Samuel Williams.
 # Copyright, 2017, by Kent Gruber.
 # Copyright, 2022, by Shannon Skipper.
 
@@ -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
@@ -33,6 +34,19 @@ module Async
 			empty?
 		end
 		
+		# Adjust the number of transient children, assuming it has changed.
+		#
+		# Despite being public, this is not intended to be called directly. It is used internally by {Node#transient=}.
+		#
+		# @parameter transient [Boolean] Whether to increment or decrement the transient count.
+		def adjust_transient_count(transient)
+			if transient
+				@transient_count += 1
+			else
+				@transient_count -= 1
+			end
+		end
+		
 		private
 		
 		def added(node)
@@ -73,7 +87,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 +101,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 +123,22 @@ module Async
 			@transient
 		end
 		
+		# Change the transient state of the node.
+		#
+		# A transient node is not considered when determining if a node is finished, and propagates up if the parent is consumed.
+		#
+		# @parameter value [Boolean] Whether the node is transient.
+		def transient=(value)
+			if @transient != value
+				@transient = value
+				
+				@parent&.children&.adjust_transient_count(value)
+			end
+		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 +153,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 +168,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 +292,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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2018-2022, by Samuel Williams.
+# Copyright, 2018-2024, by Samuel Williams.
 
 require_relative 'condition'
 
@@ -29,5 +29,7 @@ module Async
 				end
 			end
 		end
+		
+		private_constant :Signal
 	end
 end

data/lib/async/queue.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2018-2022, by Samuel Williams.
+# Copyright, 2018-2024, by Samuel Williams.
 # Copyright, 2019, by Ryan Musgrave.
 # Copyright, 2020-2022, by Bruno Sutic.
 
@@ -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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2017-2022, by Samuel Williams.
+# Copyright, 2017-2024, by Samuel Williams.
 # Copyright, 2017, by Kent Gruber.
 # Copyright, 2018, by Sokolov Yura.
 
@@ -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