async 2.24.0 → 2.28.1

data/lib/async/barrier.rb

@@ -1,10 +1,11 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2024, by Samuel Williams.
+# Copyright, 2019-2025, by Samuel Williams.
 
 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}.
@@ -16,6 +17,7 @@ module Async
 		# @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,7 +1,7 @@
 # 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.

data/lib/async/condition.rb

@@ -1,7 +1,7 @@
 # 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"
@@ -42,6 +42,8 @@ module Async
 		
 		# @deprecated Replaced by {#waiting?}
 		def empty?
+			warn("`Async::Condition#empty?` is deprecated, use `Async::Condition#waiting?` instead.", uplevel: 1, category: :deprecated) if $VERBOSE
+			
 			@waiting.empty?
 		end
 		

data/lib/async/limited_queue.rb

@@ -1,7 +1,13 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2024, by Samuel Williams.
+# 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,9 +1,10 @@
 # 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"
 
@@ -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,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2018-2024, by Samuel Williams.
+# Copyright, 2018-2025, by Samuel Williams.
 
 require_relative "condition"
 
@@ -10,12 +10,14 @@ module Async
 	# @public Since *Async v1*.
 	class Notification < Condition
 		# Signal to a given task that it should resume operations.
+		#
+		# @returns [Boolean] if a task was signalled.
 		def signal(value = nil, task: Task.current)
-			return if @waiting.empty?
+			return false if @waiting.empty?
 			
 			Fiber.scheduler.push Signal.new(self.exchange, value)
 			
-			return nil
+			return true
 		end
 		
 		Signal = Struct.new(:waiting, :value) do

data/lib/async/queue.rb

@@ -1,9 +1,11 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2018-2024, by Samuel Williams.
+# Copyright, 2018-2025, by Samuel Williams.
 # Copyright, 2019, by Ryan Musgrave.
 # Copyright, 2020-2022, by Bruno Sutic.
+# Copyright, 2025, by Jahfer Husain.
+# Copyright, 2025, by Shopify Inc.
 
 require_relative "notification"
 
@@ -14,16 +16,36 @@ module Async
 	#
 	# @public Since *Async v1*.
 	class Queue
+		# An error raised when trying to enqueue items to a closed queue.
+		# @public Since *Async v2.24*.
+		class ClosedError < RuntimeError
+		end
+		
 		# 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 = []
+			@closed = false
 			@parent = parent
 			@available = available
 		end
 		
+		# @returns [Boolean] Whether the queue is closed.
+		def closed?
+			@closed
+		end
+		
+		# Close the queue, causing all waiting tasks to return `nil`. Any subsequent calls to {enqueue} will raise an exception.
+		def close
+			@closed = true
+			
+			while @available.waiting?
+				@available.signal(nil)
+			end
+		end
+		
 		# @attribute [Array] The items in the queue.
 		attr :items
 		
@@ -39,6 +61,10 @@ module Async
 		
 		# Add an item to the queue.
 		def push(item)
+			if @closed
+				raise ClosedError, "Cannot push items to a closed queue."
+			end
+			
 			@items << item
 			
 			@available.signal unless self.empty?
@@ -51,6 +77,10 @@ module Async
 		
 		# Add multiple items to the queue.
 		def enqueue(*items)
+			if @closed
+				raise ClosedError, "Cannot enqueue items to a closed queue."
+			end
+			
 			@items.concat(items)
 			
 			@available.signal unless self.empty?
@@ -59,6 +89,10 @@ module Async
 		# Remove and return the next item from the queue.
 		def dequeue
 			while @items.empty?
+				if @closed
+					return nil
+				end
+				
 				@available.wait
 			end
 			
@@ -105,6 +139,13 @@ module Async
 	# A queue which limits the number of items that can be enqueued.
 	# @public Since *Async v1*.
 	class LimitedQueue < Queue
+		# @private This exists purely for emitting a warning.
+		def self.new(...)
+			warn("`require 'async/limited_queue'` to use `Async::LimitedQueue`.", uplevel: 1, category: :deprecated) if $VERBOSE
+			
+			super
+		end
+		
 		# Create a new limited queue.
 		#
 		# @parameter limit [Integer] The maximum number of items that can be enqueued.
@@ -119,9 +160,19 @@ module Async
 		# @attribute [Integer] The maximum number of items that can be enqueued.
 		attr :limit
 		
+		# Close the queue, causing all waiting tasks to return `nil`. Any subsequent calls to {enqueue} will raise an exception.
+		# Also signals all tasks waiting for the queue to be full.
+		def close
+			super
+			
+			while @full.waiting?
+				@full.signal(nil)
+			end
+		end
+		
 		# @returns [Boolean] Whether trying to enqueue an item would block.
 		def limited?
-			@items.size >= @limit
+			!@closed && @items.size >= @limit
 		end
 		
 		# Add an item to the queue.
@@ -148,6 +199,10 @@ module Async
 					@full.wait
 				end
 				
+				if @closed
+					raise ClosedError, "Cannot enqueue items to a closed queue."
+				end
+				
 				available = @limit - @items.size
 				@items.concat(items.shift(available))
 				

data/lib/async/reactor.rb

@@ -1,7 +1,7 @@
 # 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, 2018, by Sokolov Yura.
 
@@ -12,6 +12,8 @@ module Async
 	class Reactor < Scheduler
 		# @deprecated Replaced by {Kernel::Async}.
 		def self.run(...)
+			warn("`Async::Reactor.run{}` is deprecated, use `Async{}` instead.", uplevel: 1, category: :deprecated) if $VERBOSE
+			
 			Async(...)
 		end
 		

data/lib/async/scheduler.rb

@@ -1,14 +1,14 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2024, by Samuel Williams.
+# Copyright, 2020-2025, by Samuel Williams.
 # Copyright, 2020, by Jun Jiang.
 # Copyright, 2021, by Julien Portalier.
+# Copyright, 2025, by Shopify Inc.
 
 require_relative "clock"
 require_relative "task"
 require_relative "timeout"
-require_relative "worker_pool"
 
 require "io/event"
 
@@ -46,6 +46,28 @@ module Async
 			true
 		end
 		
+		# Used to augment the scheduler to add support for blocking operations.
+		module BlockingOperationWait
+			# Wait for the given work to be executed.
+			#
+			# @public Since *Async v2.21* and *Ruby v3.4*.
+			# @asynchronous May be non-blocking.
+			#
+			# @parameter work [Proc] The work to execute on a background thread.
+			# @returns [Object] The result of the work.
+			def blocking_operation_wait(work)
+				@worker_pool.call(work)
+			end
+		end
+		
+		private_constant :BlockingOperationWait
+		
+		if ::IO::Event.const_defined?(:WorkerPool)
+			WorkerPool = ::IO::Event::WorkerPool
+		else
+			WorkerPool = nil
+		end
+		
 		# Create a new scheduler.
 		#
 		# @public Since *Async v1*.
@@ -65,14 +87,15 @@ module Async
 			@idle_time = 0.0
 			
 			@timers = ::IO::Event::Timers.new
+			
 			if worker_pool == true
-				@worker_pool = WorkerPool.new
+				@worker_pool = WorkerPool&.new
 			else
 				@worker_pool = worker_pool
 			end
 			
 			if @worker_pool
-				self.singleton_class.prepend(WorkerPool::BlockingOperationWait)
+				self.singleton_class.prepend(BlockingOperationWait)
 			end
 		end
 		
@@ -97,7 +120,7 @@ module Async
 				return @busy_time / total_time
 			end
 		end
-	
+		
 		# Invoked when the fiber scheduler is being closed.
 		#
 		# Executes the run loop until all tasks are finished, then closes the scheduler.
@@ -234,7 +257,7 @@ module Async
 		# @parameter blocker [Object] The object that was blocking the fiber.
 		# @parameter fiber [Fiber] The fiber to unblock.
 		def unblock(blocker, fiber)
-			# $stderr.puts "unblock(#{blocker}, #{fiber})"
+			# Fiber.blocking{$stderr.puts "unblock(#{blocker}, #{fiber})"}
 			
 			# This operation is protected by the GVL:
 			if selector = @selector
@@ -250,6 +273,8 @@ module Async
 		#
 		# @parameter duration [Numeric | Nil] The time in seconds to sleep, or if nil, indefinitely.
 		def kernel_sleep(duration = nil)
+			# Fiber.blocking{$stderr.puts "kernel_sleep(#{duration}, #{Fiber.current})"}
+			
 			if duration
 				self.block(nil, duration)
 			else
@@ -348,6 +373,34 @@ module Async
 			end
 		end
 		
+		# Used to defer stopping the current task until later.
+		class FiberInterrupt
+			# Create a new stop later operation.
+			#
+			# @parameter task [Task] The task to stop later.
+			def initialize(fiber, exception)
+				@fiber = fiber
+				@exception = exception
+			end
+			
+			# @returns [Boolean] Whether the task is alive.
+			def alive?
+				@fiber.alive?
+			end
+			
+			# Transfer control to the operation - this will stop the task.
+			def transfer
+				# Fiber.blocking{$stderr.puts "FiberInterrupt#transfer(#{@fiber}, #{@exception})"}
+				@fiber.raise(@exception)
+			end
+		end
+		
+		# Raise an exception on the specified fiber, waking up the event loop if necessary.
+		def fiber_interrupt(fiber, exception)
+			# Fiber.blocking{$stderr.puts "fiber_interrupt(#{fiber}, #{exception})"}
+			unblock(nil, FiberInterrupt.new(fiber, exception))
+		end
+		
 		# Wait for the specified process ID to exit.
 		#
 		# @public Since *Async v2*.
@@ -361,6 +414,19 @@ module Async
 			return @selector.process_wait(Fiber.current, pid, flags)
 		end
 		
+		# Wait for the specified IOs to become ready for the specified events.
+		#
+		# @public Since *Async v2.25*.
+		# @asynchronous May be non-blocking.
+		def io_select(...)
+			Thread.new do
+				# Don't make unnecessary output, since we will propagate the exception:
+				Thread.current.report_on_exception = false
+				
+				::IO.select(...)
+			end.value
+		end
+		
 		# Run one iteration of the event loop.
 		#
 		# When terminating the event loop, we already know we are finished. So we don't need to check the task tree. This is a logical requirement because `run_once` ignores transient tasks. For example, a single top level transient task is not enough to keep the reactor running, but during termination we must still process it in order to terminate child tasks.
@@ -517,7 +583,8 @@ module Async
 		# @yields {|task| ...} Executed within the task.
 		# @returns [Task] The task that was scheduled into the reactor.
 		def async(*arguments, **options, &block)
-			# warn "Async::Scheduler#async is deprecated. Use `run` or `Task#async` instead.", uplevel: 1, category: :deprecated
+			# Since this method is called by `run`, this warning is too excessive:
+			# warn("Async::Scheduler#async is deprecated. Use `run` or `Task#async` instead.", uplevel: 1, category: :deprecated) if $VERBOSE
 			
 			Kernel.raise ClosedError if @selector.nil?
 			
@@ -528,6 +595,8 @@ module Async
 			return task
 		end
 		
+		# Create a new fiber and return it without starting execution.
+		# @returns [Fiber] The fiber that was created.
 		def fiber(...)
 			return async(...).fiber
 		end

data/lib/async/stop.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require "fiber"
+require "console"
+
+module Async
+	# Raised when a task is explicitly stopped.
+	class Stop < Exception
+		# Represents the source of the stop operation.
+		class Cause < Exception
+			if RUBY_VERSION >= "3.4"
+				# @returns [Array(Thread::Backtrace::Location)] The backtrace of the caller.
+				def self.backtrace
+					caller_locations(2..-1)
+				end
+			else
+				# @returns [Array(String)] The backtrace of the caller.
+				def self.backtrace
+					caller(2..-1)
+				end
+			end
+			
+			# Create a new cause of the stop operation, with the given message.
+			#
+			# @parameter message [String] The error message.
+			# @returns [Cause] The cause of the stop operation.
+			def self.for(message = "Task was stopped")
+				instance = self.new(message)
+				instance.set_backtrace(self.backtrace)
+				return instance
+			end
+		end
+		
+		if RUBY_VERSION < "3.5"
+			# Create a new stop operation.
+			#
+			# This is a compatibility method for Ruby versions before 3.5 where cause is not propagated correctly when using {Fiber#raise}
+			#
+			# @parameter message [String | Hash] The error message or a hash containing the cause.
+			def initialize(message = "Task was stopped")
+				if message.is_a?(Hash)
+					@cause = message[:cause]
+					message = "Task was stopped"
+				end
+				
+				super(message)
+			end
+			
+			# @returns [Exception] The cause of the stop operation.
+			#
+			# This is a compatibility method for Ruby versions before 3.5 where cause is not propagated correctly when using {Fiber#raise}, we explicitly capture the cause here.
+			def cause
+				super || @cause
+			end
+		end
+		
+		# 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.
+			# @parameter cause [Exception] The cause of the stop operation.
+			def initialize(task, cause = nil)
+				@task = task
+				@cause = cause
+			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(false, cause: @cause)
+			end
+		end
+	end
+end