async 2.32.0 → 2.39.0

data/lib/async/barrier.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2025, by Samuel Williams.
+# Copyright, 2019-2026, by Samuel Williams.
+# Copyright, 2026, by Tavian Barnes.
 
 require_relative "list"
 require_relative "task"
@@ -18,6 +19,7 @@ module Async
 		def initialize(parent: nil)
 			@tasks = List.new
 			@finished = Queue.new
+			@condition = Condition.new
 			
 			@parent = parent
 		end
@@ -42,18 +44,32 @@ module Async
 		
 		# Execute a child task and add it to the barrier.
 		# @asynchronous Executes the given block concurrently.
+		# @returns [Task] The task which was created to execute the block.
 		def async(*arguments, parent: (@parent or Task.current), **options, &block)
 			raise "Barrier is stopped!" if @finished.closed?
 			
 			waiting = nil
 			
-			parent.async(*arguments, **options) do |task, *arguments|
-				waiting = TaskNode.new(task)
-				@tasks.append(waiting)
+			task = parent.async(*arguments, **options) do |task, *arguments|
+				# Create a new list node for the task and add it to the list of waiting tasks:
+				node = TaskNode.new(task)
+				@tasks.append(node)
+				
+				# Signal the outer async block that we have added the task to the list of waiting tasks, and that it can now wait for it to finish:
+				waiting = node
+				@condition.signal
+				
+				# Invoke the block, which may raise an error. If it does, we will still signal that the task has finished:
 				block.call(task, *arguments)
 			ensure
-				@finished.signal(waiting) unless @finished.closed?
+				# Signal that the task has finished, which will unblock the waiting task:
+				@finished.signal(node) unless @finished.closed?
 			end
+			
+			# `parent.async` may yield before the child block executes, so we wait here until the child has appended itself to `@tasks`, ensuring `wait` cannot return early and miss tracking it:
+			@condition.wait while waiting.nil?
+			
+			return task
 		end
 		
 		# Whether there are any tasks being held by the barrier.
@@ -65,12 +81,17 @@ module Async
 		# 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.
+		# @returns [Integer | Nil] The number of tasks which were waited for, or `nil` if there were no tasks to wait for.
 		#
 		# @asynchronous Will wait for tasks to finish executing.
 		def wait
-			while !@tasks.empty?
+			return nil if @tasks.empty?
+			count = 0
+			
+			while true
 				# Wait for a task to finish (we get the task node):
-				return unless waiting = @finished.wait
+				break unless waiting = @finished.wait
+				count += 1
 				
 				# Remove the task as it is now finishing:
 				@tasks.remove?(waiting)
@@ -85,17 +106,27 @@ module Async
 					# Wait for it to either complete or raise an error:
 					task.wait
 				end
+				
+				break if @tasks.empty?
 			end
+			
+			return count
 		end
 		
-		# Stop all tasks held by the barrier.
+		# Cancel all tasks held by the barrier.
 		# @asynchronous May wait for tasks to finish executing.
-		def stop
+		def cancel
 			@tasks.each do |waiting|
-				waiting.task.stop
+				waiting.task.cancel
 			end
 			
 			@finished.close
 		end
+		
+		# Backward compatibility alias for {#cancel}.
+		# @deprecated Use {#cancel} instead.
+		def stop
+			cancel
+		end
 	end
 end

data/lib/async/cancel.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+module Async
+	# Raised when a task is explicitly cancelled.
+	class Cancel < Exception
+		# Represents the source of the cancel 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 cancel operation, with the given message.
+			#
+			# @parameter message [String] The error message.
+			# @returns [Cause] The cause of the cancel operation.
+			def self.for(message = "Task was cancelled!")
+				instance = self.new(message)
+				instance.set_backtrace(self.backtrace)
+				return instance
+			end
+		end
+		
+		if RUBY_VERSION < "3.5"
+			# Create a new cancel 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 cancelled")
+				
+				if message.is_a?(Hash)
+					@cause = message[:cause]
+					message = "Task was cancelled"
+				end
+				
+				super(message)
+			end
+			
+			# @returns [Exception] The cause of the cancel 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 cancelling the current task until later.
+		class Later
+			# Create a new cancel later operation.
+			#
+			# @parameter task [Task] The task to cancel later.
+			# @parameter cause [Exception] The cause of the cancel 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 cancel the task.
+			def transfer
+				@task.cancel(false, cause: @cause)
+			end
+		end
+	end
+end

data/lib/async/clock.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2018-2025, by Samuel Williams.
+# Copyright, 2018-2026, by Samuel Williams.
+# Copyright, 2026, by Shopify Inc.
 
 module Async
 	# A convenient wrapper around the internal monotonic clock.
@@ -36,6 +37,9 @@ module Async
 			@started = nil
 		end
 		
+		# @returns [Numeric | Nil] The time when the clock was started, or nil if not started.
+		attr :started
+		
 		# Start measuring a duration.
 		def start!
 			@started ||= Clock.now
@@ -70,5 +74,22 @@ module Async
 				@started = Clock.now
 			end
 		end
+		
+		# Convert the clock to a JSON-compatible hash.
+		#
+		# @returns [Hash] The JSON-compatible hash.
+		def as_json(...)
+			{
+				started: self.started,
+				total: self.total,
+			}
+		end
+		
+		# Convert the clock to a JSON string.
+		#
+		# @returns [String] The JSON string.
+		def to_json(...)
+			self.as_json.to_json(...)
+		end
 	end
 end

data/lib/async/deadline.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
+# Copyright, 2025, by Shopify Inc.
 # Copyright, 2025, by Samuel Williams.
 
 require_relative "clock"

data/lib/async/error.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+module Async
+	# Raised if a timeout occurs on a specific Fiber. Handled gracefully by `Task`.
+	# @public Since *Async v1*.
+	class TimeoutError < StandardError
+		# Create a new timeout error.
+		#
+		# @parameter message [String] The error message.
+		def initialize(message = "execution expired")
+			super
+		end
+	end
+end

data/lib/async/fork_handler.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025-2026, by Shopify Inc.
+# Copyright, 2025-2026, by Samuel Williams.
+
+module Async
+	# Private module that hooks into Process._fork to handle fork events.
+	#
+	# If `Scheduler#process_fork` hook is adopted in Ruby 4, this code can be removed after Ruby < 4 is no longer supported.
+	module ForkHandler
+		def _fork(&block)
+			result = super
+			
+			if result.zero?
+				# Child process:
+				if Fiber.scheduler.respond_to?(:process_fork)
+					Fiber.scheduler.process_fork
+				end
+			end
+			
+			return result
+		end
+	end
+	
+	private_constant :ForkHandler
+	
+	# Hook into Process._fork to handle fork events automatically:
+	unless RUBY_VERSION > "4"
+		::Process.singleton_class.prepend(ForkHandler)
+	end
+end

data/lib/async/idler.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2024, by Samuel Williams.
+# Copyright, 2024-2025, by Samuel Williams.
 
 module Async
 	# A load balancing mechanism that can be used process work when the system is idle.
@@ -13,10 +13,13 @@ module Async
 		# @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)
+		def initialize(maximum_load = 0.8, backoff: 0.001, parent: nil)
 			@maximum_load = maximum_load
 			@backoff = backoff
+			@current = backoff
+			
 			@parent = parent
+			@mutex = Mutex.new
 		end
 		
 		# Wait until the system is idle, then execute the given block in a new task.
@@ -38,20 +41,29 @@ module Async
 		#
 		# 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
-				
-				break if load < @maximum_load
+			@mutex.synchronize do
+				scheduler = Fiber.scheduler
 				
-				if backoff
-					sleep(backoff)
-					backoff *= 2.0
-				else
-					scheduler.yield
-					backoff = @backoff
+				while true
+					load = scheduler.load
+					
+					if load <= @maximum_load
+						# Even though load is okay, if @current is high, we were recently overloaded. Sleep proportionally to prevent burst after load drop:
+						if @current > @backoff
+							# Sleep a fraction of @current to rate limit:
+							sleep(@current - @backoff)
+							
+							# Decay @current gently towards @backoff:
+							alpha = 0.99
+							@current *= alpha + (1.0 - alpha) * (load / @maximum_load)
+						end
+						
+						break
+					else
+						# We're overloaded, so increase backoff:
+						@current *= (load / @maximum_load)
+						sleep(@current)
+					end
 				end
 			end
 		end

data/lib/async/loop.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "console"
+
+module Async
+	# @namespace
+	module Loop
+		# Execute a block repeatedly at quantized (time-aligned) intervals.
+		#
+		# The alignment is computed modulo the current clock time in seconds. For example, with
+		# `interval: 60`, executions will occur at 00:00, 01:00, 02:00, etc., regardless of when
+		# the loop is started. With `interval: 300` (5 minutes), executions align to 00:00, 00:05,
+		# 00:10, etc.
+		#
+		# This is particularly useful for tasks that should run at predictable wall-clock times,
+		# such as metrics collection, periodic cleanup, or scheduled jobs that need to align
+		# across multiple processes.
+		#
+		# If an error occurs during block execution, it is logged and the loop continues.
+		#
+		# @example Run every minute at :00 seconds:
+		# 	Async::Loop.quantized(interval: 60) do
+		# 		puts "Current time: #{Time.now}"
+		# 	end
+		#
+		# @example Run every 5 minutes aligned to the hour:
+		# 	Async::Loop.quantized(interval: 300) do
+		# 		collect_metrics
+		# 	end
+		#
+		# @parameter interval [Numeric] The interval in seconds. Executions will align to multiples of this interval based on the current time.
+		# @yields The block to execute at each interval.
+		#
+		# @public Since *Async v2.37*.
+		def self.quantized(interval: 60, &block)
+			while true
+				# Compute the wait time to the next interval:
+				wait = interval - (Time.now.to_f % interval)
+				if wait.positive?
+					# Sleep until the next interval boundary:
+					sleep(wait)
+				end
+				
+				begin
+					yield
+				rescue => error
+					Console.error(self, "Loop error:", error)
+				end
+			end
+		end
+		
+		# Execute a block repeatedly with a fixed delay between executions.
+		#
+		# Unlike {quantized}, this method waits for the specified interval *after* each execution
+		# completes. This means the actual time between the start of successive executions will be
+		# `interval + execution_time`.
+		#
+		# If an error occurs during block execution, it is logged and the loop continues.
+		#
+		# @example Run every 5 seconds (plus execution time):
+		# 	Async::Loop.periodic(interval: 5) do
+		# 		process_queue
+		# 	end
+		#
+		# @parameter interval [Numeric] The delay in seconds between executions.
+		# @yields The block to execute periodically.
+		#
+		# @public Since *Async v2.37*.
+		def self.periodic(interval: 60, &block)
+			while true
+				begin
+					yield
+				rescue => error
+					Console.error(self, "Loop error:", error)
+				end
+				
+				sleep(interval)
+			end
+		end
+	end
+end

data/lib/async/node.rb

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2017-2025, by Samuel Williams.
+# Copyright, 2017-2026, by Samuel Williams.
 # Copyright, 2017, by Kent Gruber.
 # Copyright, 2022, by Shannon Skipper.
-# Copyright, 2025, by Shopify Inc.
+# Copyright, 2025-2026, by Shopify Inc.
 
 require "fiber/annotation"
 
@@ -214,7 +214,8 @@ module Async
 		end
 		
 		protected def remove_child(child)
-			@children.remove(child)
+			# In the case of a fork, the children list may be nil:
+			@children&.remove(child)
 			child.set_parent(nil)
 		end
 		
@@ -279,26 +280,44 @@ module Async
 			return @children.nil?
 		end
 		
-		# Attempt to stop the current node immediately, including all non-transient children. Invokes {#stop_children} to stop all children.
+		# Attempt to cancel the current node immediately, including all non-transient children. Invokes {#stop_children} to cancel all children.
 		#
-		# @parameter later [Boolean] Whether to defer stopping until some point in the future.
-		def stop(later = false)
+		# @parameter later [Boolean] Whether to defer cancelling until some point in the future.
+		def cancel(later = false)
 			# The implementation of this method may defer calling `stop_children`.
 			stop_children(later)
 		end
 		
+		# Backward compatibility alias for {#cancel}.
+		# @deprecated Use {#cancel} instead.
+		def stop(...)
+			cancel(...)
+		end
+		
 		# Attempt to stop all non-transient children.
 		private def stop_children(later = false)
 			@children&.each do |child|
-				child.stop(later) unless child.transient?
+				child.cancel(later) unless child.transient?
 			end
 		end
 		
-		# Whether the node has been stopped.
-		def stopped?
+		# Wait for this node to complete. By default, nodes cannot be waited on.
+		# Subclasses like Task override this method to provide waiting functionality.
+		def wait
+			nil
+		end
+		
+		# Whether the node has been cancelled.
+		def cancelled?
 			@children.nil?
 		end
 		
+		# Backward compatibility alias for {#cancelled?}.
+		# @deprecated Use {#cancelled?} instead.
+		def stopped?
+			cancelled?
+		end
+		
 		# Print the hierarchy of the task tree from the given node.
 		#
 		# @parameter out [IO] The output stream to write to.