async 2.17.0 → 2.32.0

data/lib/async/barrier.rb

@@ -1,21 +1,23 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2022, by Samuel Williams.
+# Copyright, 2019-2025, by Samuel Williams.
 
-require_relative 'list'
-require_relative 'task'
+require_relative "list"
+require_relative "task"
+require_relative "queue"
 
 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
+			@finished = Queue.new
 			
 			@parent = parent
 		end
@@ -41,11 +43,17 @@ module Async
 		# 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)
+			raise "Barrier is stopped!" if @finished.closed?
 			
-			@tasks.append(TaskNode.new(task))
+			waiting = nil
 			
-			return task
+			parent.async(*arguments, **options) do |task, *arguments|
+				waiting = TaskNode.new(task)
+				@tasks.append(waiting)
+				block.call(task, *arguments)
+			ensure
+				@finished.signal(waiting) unless @finished.closed?
+			end
 		end
 		
 		# Whether there are any tasks being held by the barrier.
@@ -55,14 +63,27 @@ module Async
 		end
 		
 		# 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.
+		#
+		# @yields {|task| ...} If a block is given, the unwaited task is yielded. You must invoke {Task#wait} yourself. In addition, you may `break` if you have captured enough results.
+		#
 		# @asynchronous Will wait for tasks to finish executing.
 		def wait
-			@tasks.each do |waiting|
+			while !@tasks.empty?
+				# Wait for a task to finish (we get the task node):
+				return unless waiting = @finished.wait
+				
+				# Remove the task as it is now finishing:
+				@tasks.remove?(waiting)
+				
+				# Get the task:
 				task = waiting.task
-				begin
+				
+				# If a block is given, the user can implement their own behaviour:
+				if block_given?
+					yield task
+				else
+					# Wait for it to either complete or raise an error:
 					task.wait
-				ensure
-					@tasks.remove?(waiting) unless task.alive?
 				end
 			end
 		end
@@ -73,6 +94,8 @@ module Async
 			@tasks.each do |waiting|
 				waiting.task.stop
 			end
+			
+			@finished.close
 		end
 	end
 end

data/lib/async/clock.rb

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2018-2022, by Samuel Williams.
+# Copyright, 2018-2025, by Samuel Williams.
 
 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,75 +1,59 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2017-2024, by Samuel Williams.
+# Copyright, 2017-2025, 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
+			@ready = ::Thread::Queue.new
 		end
 		
-		class FiberNode < List::Node
-			def initialize(fiber)
-				@fiber = fiber
-			end
-			
-			def transfer(*arguments)
-				@fiber.transfer(*arguments)
-			end
-			
-			def alive?
-				@fiber.alive?
-			end
-		end
-		
-		private_constant :FiberNode
-		
 		# Queue up the current fiber and wait on yielding the task.
 		# @returns [Object]
 		def wait
-			@waiting.stack(FiberNode.new(Fiber.current)) do
-				Fiber.scheduler.transfer
-			end
+			@ready.pop
 		end
 		
-		# @deprecated Replaced by {#waiting?}
+		# @returns [Boolean] If there are no fibers waiting on this condition.
 		def empty?
-			@waiting.empty?
+			@ready.num_waiting.zero?
 		end
 		
 		# @returns [Boolean] Is any fiber waiting on this notification?
 		def waiting?
-			@waiting.size > 0
+			!self.empty?
 		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)
-			return if @waiting.empty?
+			return if empty?
 			
-			waiting = self.exchange
+			ready = self.exchange
 			
-			waiting.each do |fiber|
-				Fiber.scheduler.resume(fiber, value) if fiber.alive?
+			ready.num_waiting.times do
+				ready.push(value)
 			end
 			
+			ready.close
+			
 			return nil
 		end
 		
 		protected
 		
 		def exchange
-			waiting = @waiting
-			@waiting = List.new
-			return waiting
+			ready = @ready
+			@ready = ::Thread::Queue.new
+			return ready
 		end
 	end
 end

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/deadline.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require_relative "clock"
+
+# @namespace
+module Async
+	# Represents a deadline timeout with decrementing remaining time.
+	# Includes an efficient representation for zero (non-blocking) timeouts.
+	# @public Since *Async v2.31*.
+	class Deadline
+		# Singleton module for immediate timeouts (zero or negative).
+		# Avoids object allocation for fast path (non-blocking) timeouts.
+		module Zero
+			# Check if the deadline has expired.
+			# @returns [Boolean] Always returns true since zero timeouts are immediately expired.
+			def self.expired?
+				true
+			end
+			
+			# Get the remaining time.
+			# @returns [Integer] Always returns 0 since zero timeouts have no remaining time.
+			def self.remaining
+				0
+			end
+		end
+		
+		# Create a deadline for the given timeout.
+		# @parameter timeout [Numeric | Nil] The timeout duration, or nil for no timeout.
+		# @returns [Deadline | Nil] A deadline instance, Zero singleton, or nil.
+		def self.start(timeout)
+			if timeout.nil?
+				nil
+			elsif timeout <= 0
+				Zero
+			else
+				self.new(timeout)
+			end
+		end
+		
+		# Create a new deadline with the specified remaining time.
+		# @parameter remaining [Numeric] The initial remaining time.
+		def initialize(remaining)
+			@remaining = remaining
+			@start = Clock.now
+		end
+		
+		# Get the remaining time, updating internal state.
+		# Each call to this method advances the internal clock and reduces
+		# the remaining time by the elapsed duration since the last call.
+		# @returns [Numeric] The remaining time (may be negative if expired).
+		def remaining
+			now = Clock.now
+			delta = now - @start
+			@start = now
+			
+			@remaining -= delta
+			
+			return @remaining
+		end
+		
+		# Check if the deadline has expired.
+		# @returns [Boolean] True if no time remains.
+		def expired?
+			self.remaining <= 0
+		end
+	end
+end

data/lib/async/idler.rb

@@ -7,7 +7,8 @@ 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`.
+		#
+		# @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.

data/lib/async/limited_queue.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+# The implementation lives in `queue.rb` but later we may move it here for better autoload/inference.
+require_relative "queue"
+
+module Async
+	class LimitedQueue < Queue
+		singleton_class.remove_method(:new)
+	end
+end

data/lib/async/list.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2022-2024, by Samuel Williams.
+# Copyright, 2022-2025, by Samuel Williams.
+# Copyright, 2025, by Shopify Inc.
 
 module Async
 	# A general doublely linked list. This is used internally by {Async::Barrier} and {Async::Condition} to manage child tasks.
@@ -18,6 +19,7 @@ module Async
 			sprintf("#<%s:0x%x size=%d>", self.class.name, object_id, @size)
 		end
 		
+		# @returns [String] A short summary of the list.
 		alias inspect to_s
 		
 		# Fast, safe, unbounded accumulation of children.
@@ -134,7 +136,7 @@ module Async
 			return removed(node)
 		end
 		
-		# @returns [Boolean] Returns true if the list is empty.
+		# @returns [Boolean] True if the list is empty.
 		def empty?
 			@size == 0
 		end
@@ -143,26 +145,26 @@ module Async
 		# 	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
@@ -238,6 +240,12 @@ module Async
 			attr_accessor :head
 			attr_accessor :tail
 			
+			# @returns [String] A string representation of the node.
+			def to_s
+				sprintf("#<%s:0x%x>", self.class.name, object_id)
+			end
+			
+			# @returns [String] A string representation of the node.
 			alias inspect to_s
 		end
 		

data/lib/async/node.rb

@@ -1,13 +1,14 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2017-2024, by Samuel Williams.
+# Copyright, 2017-2025, by Samuel Williams.
 # Copyright, 2017, by Kent Gruber.
 # Copyright, 2022, by Shannon Skipper.
+# Copyright, 2025, by Shopify Inc.
 
-require 'fiber/annotation'
+require "fiber/annotation"
 
-require_relative 'list'
+require_relative "list"
 
 module Async
 	# A list of children tasks.
@@ -180,6 +181,7 @@ module Async
 			"\#<#{self.description}>"
 		end
 		
+		# @returns [String] A description of the node.
 		alias inspect to_s
 		
 		# Change the parent of this node.

data/lib/async/notification.rb

@@ -1,32 +1,36 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2018-2024, by Samuel Williams.
+# Copyright, 2018-2025, 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)
-			return if @waiting.empty?
+		#
+		# @returns [Boolean] if a task was signalled.
+		def signal(value = nil)
+			return false if empty?
 			
 			Fiber.scheduler.push Signal.new(self.exchange, value)
 			
-			return nil
+			return true
 		end
 		
-		Signal = Struct.new(:waiting, :value) do
+		Signal = Struct.new(:ready, :value) do
 			def alive?
 				true
 			end
 			
 			def transfer
-				waiting.each do |fiber|
-					fiber.transfer(value) if fiber.alive?
+				ready.num_waiting.times do
+					ready.push(value)
 				end
+				
+				ready.close
 			end
 		end