async 2.12.1 → 2.22.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1eef4bf800b6d52c0f273289186f9886975237ecdf9885f599617691283ca2e5
-  data.tar.gz: 14a7e20dc72c178b89a93233a73fd49f182f7aec7926804b9b8bf37e8ceb9f36
+  metadata.gz: ef8aa467e82d3ddcd2c24a823ffba2e2b9e1680d005fade667ef36c882588dd1
+  data.tar.gz: c2df7e4669fe9d2f0bb8d6c6f7de673d1a89e41d8ffc99bf702f79cefbce7a3e
 SHA512:
-  metadata.gz: 30176358a5c9efc3df3e525e0ba941f5771bb7619bef28e1b6229a547ad3a24cb5475483a257704c3eea2d9214dcca2e17932994e0859a1c5d4dfc6401b24d48
-  data.tar.gz: 8b7353cf2ef0884c78a919775b84280d3234c7868c6c3b95aa00ae560a5825a07bd9533eda1afcc9776d1c94b7cc116e549e24144e4bab7c9bb3f086782a7456
+  metadata.gz: 2a98aaf33872cafab28e41acf187425926a3e0423ee5017bfd42fef66e64f55ad0ec6d6d1a053987813a3f190471e4521bac7c8895fb1ee352b8e984cf1dd326
+  data.tar.gz: 64205b564a8de8aeb22d0ae6834ea9dfd114439336e7bd076de489da0e045f002a9d90f51f72414c36ed006a599cd536d27ff852b5f8f9541f3c656c3d9e7035

data/lib/async/barrier.md

@@ -18,7 +18,7 @@ Sync do
 	# Sleep sort the numbers:
 	numbers.each do |number|
 		barrier.async do |task|
-			task.sleep(number)
+			sleep(number)
 			sorted << number
 		end
 	end

data/lib/async/barrier.rb

@@ -1,19 +1,19 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2022, by Samuel Williams.
+# Copyright, 2019-2024, by Samuel Williams.
 
-require_relative 'list'
-require_relative 'task'
+require_relative "list"
+require_relative "task"
 
 module Async
 	# A general purpose synchronisation primitive, which allows one task to wait for a number of other tasks to complete. It can be used in conjunction with {Semaphore}.
 	#
-	# @public Since `stable-v1`.
+	# @public Since *Async v1*.
 	class Barrier
 		# Initialize the barrier.
 		# @parameter parent [Task | Semaphore | Nil] The parent for holding any children tasks.
-		# @public Since `stable-v1`.
+		# @public Since *Async v1*.
 		def initialize(parent: nil)
 			@tasks = List.new
 			

data/lib/async/clock.rb

@@ -5,7 +5,7 @@
 
 module Async
 	# A convenient wrapper around the internal monotonic clock.
-	# @public Since `stable-v1`.
+	# @public Since *Async v1*.
 	class Clock
 		# Get the current elapsed monotonic time.
 		def self.now
@@ -61,5 +61,14 @@ module Async
 			
 			return total
 		end
+		
+		# Reset the total elapsed time. If the clock is currently running, reset the start time to now.
+		def reset!
+			@total = 0
+			
+			if @started
+				@started = Clock.now
+			end
+		end
 	end
 end

data/lib/async/condition.md

@@ -15,7 +15,7 @@ Sync do
 	end
 	
 	Async do |task|
-		task.sleep(1)
+		sleep(1)
 		Console.info "Signalling condition..."
 		condition.signal("Hello World")
 	end

data/lib/async/condition.rb

@@ -1,16 +1,17 @@
 # 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'
-require_relative 'list'
+require "fiber"
+require_relative "list"
 
 module Async
 	# A synchronization primitive, which allows fibers to wait until a particular condition is (edge) triggered.
-	# @public Since `stable-v1`.
+	# @public Since *Async v1*.
 	class Condition
+		# Create a new condition.
 		def initialize
 			@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/console.rb

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

data/lib/async/idler.rb

@@ -4,13 +4,29 @@
 # 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 *Async v2*.
+		#
+		# @parameter maximum_load [Numeric] The maximum load before we start shedding work.
+		# @parameter backoff [Numeric] The initial backoff time, used for delaying work.
+		# @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 +34,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/limited_queue.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2024, by Samuel Williams.
+
+# The implementation lives in `queue.rb` but later we may move it here for better autoload/inference.
+require_relative "queue"

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,17 +1,18 @@
 # 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.
 
-require 'fiber/annotation'
+require "fiber/annotation"
 
-require_relative 'list'
+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,13 +1,13 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2018-2022, by Samuel Williams.
+# Copyright, 2018-2024, by Samuel Williams.
 
-require_relative 'condition'
+require_relative "condition"
 
 module Async
 	# A synchronization primitive, which allows fibers to wait until a notification is received. Does not block the task which signals the notification. Waiting tasks are resumed on next iteration of the reactor.
-	# @public Since `stable-v1`.
+	# @public Since *Async v1*.
 	class Notification < Condition
 		# Signal to a given task that it should resume operations.
 		def signal(value = nil, task: Task.current)
@@ -29,5 +29,7 @@ module Async
 				end
 			end
 		end
+		
+		private_constant :Signal
 	end
 end

data/lib/async/queue.rb

@@ -1,76 +1,122 @@
 # 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.
 
-require_relative 'notification'
+require_relative "notification"
 
 module Async
 	# A queue which allows items to be processed in order.
-	# @public Since `stable-v1`.
-	class Queue < Notification
-		def initialize(parent: nil)
-			super()
-			
+	#
+	# It has a compatible interface with {Notification} and {Condition}, except that it's multi-value.
+	#
+	# @public Since *Async v1*.
+	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
 		
-		def <<(item)
+		# Add an item to the queue.
+		def push(item)
 			@items << item
 			
-			self.signal unless self.empty?
+			@available.signal unless self.empty?
 		end
 		
+		# Compatibility with {::Queue#push}.
+		def <<(item)
+			self.push(item)
+		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)
+		# Compatibility with {::Queue#pop}.
+		def pop
+			self.dequeue
+		end
+		
+		# 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 = nil)
+			self.enqueue(value)
+		end
+		
+		# Wait for an item to be available, the same as {#dequeue}.
+		def wait
+			self.dequeue
+		end
 	end
 	
-	# @public Since `stable-v1`.
+	# A queue which limits the number of items that can be enqueued.
+	# @public Since *Async 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,7 +124,12 @@ module Async
 			@items.size >= @limit
 		end
 		
-		def <<(item)
+		# 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 push(item)
 			while limited?
 				@full.wait
 			end
@@ -86,7 +137,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 +151,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,11 +1,11 @@
 # 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.
 
-require_relative 'scheduler'
+require_relative "scheduler"
 
 module Async
 	# A wrapper around the the scheduler which binds it to the current thread automatically.
@@ -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