async 2.36.0 → 2.38.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b514097c721290749f38fed73721c5cb6d17af2a8af189f5a8e537f7b30c14d3
-  data.tar.gz: 3eba30b0a03bdb9f9da1d1e4eeb6b11ec3224c0f3d02f27cc07ac1e5e7d7a41e
+  metadata.gz: 847417a49140235dad0d6e2b063dd6a3465247cb7b3000708d58bd01adbcffb1
+  data.tar.gz: f79a5b29cd8e10bdfe7f10ba24f0fb850bb0856e8612dffcecdd7882c133bc61
 SHA512:
-  metadata.gz: 9ea8d371279ec9bf8feeaa85895f25733247c8ecb059d599f34e8ecc85b4b124c05dee5421414d28c24316d7c4e69bdff622c31b182e9f883456836a6aab17ed
-  data.tar.gz: 55ddefa4f011c2dccf235043cad5ad334418c394ced59a960b993d18ead0850f7d60875a3edbdc55418d3a9d3045cef1d607170fea0ae484f4dc62bc13f15ca2
+  metadata.gz: c0b69a0ff96474b52956268018bf8a08aa147aff8c0c80c60185cd070f7d3d36360f3b9f2f8ae1d082a0ee8d4fc172621323bd1e99de5a8ea946f7263761e120
+  data.tar.gz: 80c5f6e6e946b3675ad55cc40ae30ff860aeb08dd732a5d87e2350a4c6ac48d6619c434900e39f9012a76d398930debb56c8d183ef9e139a62138b060a0b24bc

data/context/scheduler.md

@@ -38,7 +38,7 @@ Async do |task|
 	task.print_hierarchy($stderr)
 	
 	# Kill the subtask
-	subtask.stop
+	subtask.cancel
 end
 ~~~
 
@@ -69,9 +69,9 @@ end
 
 You can use this approach to embed the reactor in another event loop. For some integrations, you may want to specify the maximum time to wait to {ruby Async::Scheduler#run_once}.
 
-### Stopping a Scheduler
+### Cancelling a Scheduler
 
-{ruby Async::Scheduler#stop} will stop the current scheduler and all children tasks.
+{ruby Async::Scheduler#cancel} will cancel the current scheduler and all children tasks.
 
 ### Fiber Scheduler Integration
 

data/context/tasks.md

@@ -4,7 +4,7 @@ This guide explains how asynchronous tasks work and how to use them.
 
 ## Overview
 
-Tasks are the smallest unit of sequential code execution in {ruby Async}. Tasks can create other tasks, and Async tracks the parent-child relationship between tasks. When a parent task is stopped, it will also stop all its children tasks. The reactor always starts with one root task.
+Tasks are the smallest unit of sequential code execution in {ruby Async}. Tasks can create other tasks, and Async tracks the parent-child relationship between tasks. When a parent task is cancelled, it will also cancel all its children tasks. The reactor always starts with one root task.
 
 ```mermaid
 graph LR
@@ -23,11 +23,11 @@ graph LR
 
 A fiber is a lightweight unit of execution that can be suspended and resumed at specific points. After a fiber is suspended, it can be resumed later at the same point with the same execution state. Because only one fiber can execute at a time, they are often referred to as a mechanism for cooperative concurrency.
 
-A task provides extra functionality on top of fibers. A task behaves like a promise: it either succeeds with a value or fails with an exception. Tasks keep track of their parent-child relationships, and when a parent task is stopped, it will also stop all its children tasks. This makes it easier to create complex programs with many concurrent tasks.
+A task provides extra functionality on top of fibers. A task behaves like a promise: it either succeeds with a value or fails with an exception. Tasks keep track of their parent-child relationships, and when a parent task is cancelled, it will also cancel all its children tasks. This makes it easier to create complex programs with many concurrent tasks.
 
 ### Why does Async manipulate tasks and not fibers?
 
-The {ruby Async::Scheduler} actually works directly with fibers for most operations and isn't aware of tasks. However, the reactor does maintain a tree of tasks for the purpose of managing task and reactor life-cycle. For example, stopping a parent task will stop all its children tasks, and the reactor will exit when all tasks are finished.
+The {ruby Async::Scheduler} actually works directly with fibers for most operations and isn't aware of tasks. However, the reactor does maintain a tree of tasks for the purpose of managing task and reactor life-cycle. For example, cancelling a parent task will cancel all its children tasks, and the reactor will exit when all tasks are finished.
 
 ## Task Lifecycle
 
@@ -40,20 +40,20 @@ stateDiagram-v2
     
     running --> failed : unhandled StandardError-derived exception
     running --> complete : user code finished
-    running --> stopped : stop
+    running --> cancelled : cancel
 
-    initialized --> stopped : stop
+    initialized --> cancelled : cancel
     
     failed --> [*]
     complete --> [*]
-    stopped --> [*]
+    cancelled --> [*]
 ```
 
-Tasks are created in the `initialized` state, and are run by the reactor. During the execution, a task can either `complete` successfully, become `failed` with an unhandled `StandardError`-derived exception, or be explicitly `stopped`. In all of these cases, you can wait for a task to complete by using {ruby Async::Task#wait}.
+Tasks are created in the `initialized` state, and are run by the reactor. During the execution, a task can either `complete` successfully, become `failed` with an unhandled `StandardError`-derived exception, or be explicitly `cancelled`. In all of these cases, you can wait for a task to complete by using {ruby Async::Task#wait}.
 
 1. In the case the task successfully completed, the result will be whatever value was generated by the last expression in the task.
 2. In the case the task failed with an unhandled `StandardError`-derived exception, waiting on the task will re-raise the exception.
-3. In the case the task was stopped, the result will be `nil`.
+3. In the case the task was cancelled, the result will be `nil`.
 
 ## Starting A Task
 
@@ -175,8 +175,8 @@ Async do
 			break if done.size >= 2
 		end
 	ensure
-		# The remainder of the tasks will be stopped:
-		barrier.stop
+		# The remainder of the tasks will be cancelled:
+		barrier.cancel
 	end
 end
 ```
@@ -199,18 +199,18 @@ begin
 	# Wait until all jobs are done:
 	barrier.wait
 ensure
-	# Stop any remaining jobs:
-	barrier.stop
+	# Cancel any remaining jobs:
+	barrier.cancel
 end
 ~~~
 
-## Stopping a Task
+## Cancelling a Task
 
 When a task completes execution, it will enter the `complete` state (or the `failed` state if it raises an unhandled exception).
 
-There are various situations where you may want to stop a task ({ruby Async::Task#stop}) before it completes. The most common case is shutting down a server. A more complex example is this: you may fan out multiple (10s, 100s) of requests, wait for a subset to complete (e.g. the first 5 or all those that complete within a given deadline), and then stop (terminate/cancel) the remaining operations.
+There are various situations where you may want to cancel a task ({ruby Async::Task#cancel}) before it completes. The most common case is shutting down a server. A more complex example is this: you may fan out multiple (10s, 100s) of requests, wait for a subset to complete (e.g. the first 5 or all those that complete within a given deadline), and then cancel the remaining operations.
 
-Using the above program as an example, let's stop all the tasks just after the first one completes.
+Using the above program as an example, let's cancel all the tasks just after the first one completes.
 
 ```ruby
 Async do
@@ -221,14 +221,14 @@ Async do
 		end
 	end
 	
-	# Stop all the above tasks:
-	tasks.each(&:stop)
+	# Cancel all the above tasks:
+	tasks.each(&:cancel)
 end
 ```
 
-### Stopping all Tasks held in a Barrier
+### Cancelling all Tasks held in a Barrier
 
-To stop (terminate/cancel) all the tasks held in a barrier:
+To cancel all the tasks held in a barrier:
 
 ```ruby
 barrier = Async::Barrier.new
@@ -241,11 +241,11 @@ Async do
 		end
 	end
 	
-	barrier.stop
+	barrier.cancel
 end
 ```
 
-Unless your tasks all rescue and suppresses `StandardError`-derived exceptions, be sure to call ({ruby Async::Barrier#stop}) to stop the remaining tasks:
+Unless your tasks all rescue and suppresses `StandardError`-derived exceptions, be sure to call ({ruby Async::Barrier#cancel}) to cancel the remaining tasks:
 
 ```ruby
 barrier = Async::Barrier.new
@@ -261,7 +261,7 @@ Async do
 	begin
 		barrier.wait
 	ensure
-		barrier.stop
+		barrier.cancel
 	end
 end
 ```
@@ -273,10 +273,10 @@ In order to ensure your resources are cleaned up correctly, make sure you wrap r
 ~~~ ruby
 Async do
 	begin
-		socket = connect(remote_address) # May raise Async::Stop
+		socket = connect(remote_address) # May raise Async::Cancel
 
-		socket.write(...) # May raise Async::Stop
-		socket.read(...) # May raise Async::Stop
+		socket.write(...) # May raise Async::Cancel
+		socket.read(...) # May raise Async::Cancel
 	ensure
 		socket.close if socket
 	end
@@ -398,9 +398,9 @@ end
 
 Transient tasks are similar to normal tasks, except for the following differences:
 
-1. They are not considered by {ruby Async::Task#finished?}, so they will not keep the reactor alive. Instead, they are stopped (with a {ruby Async::Stop} exception) when all other (non-transient) tasks are finished.
+1. They are not considered by {ruby Async::Task#finished?}, so they will not keep the reactor alive. Instead, they are cancelled (with a {ruby Async::Cancel} exception) when all other (non-transient) tasks are finished.
 2. As soon as a parent task is finished, any transient child tasks will be moved up to be children of the parent's parent. This ensures that they never keep a sub-tree alive.
-3. Similarly, if you `stop` a task, any transient child tasks will be moved up the tree as above rather than being stopped.
+3. Similarly, if you `cancel` a task, any transient child tasks will be moved up the tree as above rather than being cancelled.
 
 The purpose of transient tasks is when a task is an implementation detail of an object or instance, rather than a concurrency process. Some examples of transient tasks:
 
@@ -439,7 +439,7 @@ class TimeStringCache
 				sleep(1)
 			end
 		ensure
-			# When the reactor terminates all tasks, `Async::Stop` will be raised from `sleep` and  this code will be invoked. By clearing `@refresh`, we ensure that the task will be recreated if needed again:
+			# When the reactor terminates all tasks, `Async::Cancel` will be raised from `sleep` and  this code will be invoked. By clearing `@refresh`, we ensure that the task will be recreated if needed again:
 			@refresh = nil
 		end
 	end

data/lib/async/barrier.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2025, by Samuel Williams.
+# Copyright, 2019-2026, by Samuel Williams.
 
 require_relative "list"
 require_relative "task"
@@ -88,14 +88,20 @@ module Async
 			end
 		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.

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

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2025, by Shopify Inc.
-# Copyright, 2025, by Samuel Williams.
+# 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.

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"
 
@@ -280,18 +280,24 @@ 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
 		
@@ -301,11 +307,17 @@ module Async
 			nil
 		end
 		
-		# Whether the node has been stopped.
-		def stopped?
+		# 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.

data/lib/async/promise.rb

@@ -4,6 +4,10 @@
 # Copyright, 2025, by Shopify Inc.
 # Copyright, 2025-2026, by Samuel Williams.
 
+require_relative "error"
+require_relative "deadline"
+require_relative "cancel"
+
 module Async
 	# A promise represents a value that will be available in the future.
 	# Unlike Condition, once resolved (or rejected), all future waits return immediately 
@@ -74,33 +78,92 @@ module Async
 			@mutex.synchronize{@resolved ? @value : nil}
 		end
 		
+		# Wait indefinitely for the promise to be resolved.
+		private def wait_indefinitely
+			until @resolved
+				@condition.wait(@mutex)
+			end
+		end
+		
+		# Wait for the promise to be resolved, respecting the deadline timeout.
+		# @parameter timeout [Numeric] The timeout duration.
+		# @returns [Boolean] True if resolved, false if timeout expires.
+		private def wait_with_timeout(timeout)
+			# Create deadline for timeout tracking:
+			deadline = Deadline.start(timeout)
+			
+			# Handle immediate timeout (non-blocking):
+			if deadline == Deadline::Zero && !@resolved
+				return false
+			end
+			
+			# Wait with deadline tracking:
+			until @resolved
+				# Get remaining time for this wait iteration:
+				remaining = deadline.remaining
+				
+				# Check if deadline has expired before waiting:
+				if remaining <= 0
+					return false
+				end
+				
+				@condition.wait(@mutex, remaining)
+			end
+			
+			return true
+		end
+		
+		# Wait for the promise to be resolved (without raising exceptions).
+		#
+		# If already resolved, returns immediately. Otherwise, waits until resolution or timeout.
+		#
+		# @parameter timeout [Numeric | Nil] Maximum time to wait. If nil, waits indefinitely. If 0, returns immediately if not resolved.
+		# @returns [Boolean] True if the promise is resolved, false if timeout expires
+		def wait?(timeout: nil)
+			unless @resolved
+				@mutex.synchronize do
+					# Increment waiting count:
+					@waiting += 1
+					
+					begin
+						# Wait for resolution if not already resolved:
+						unless @resolved
+							if timeout.nil?
+								wait_indefinitely
+							else
+								unless wait_with_timeout(timeout)
+									# We don't want to race on @resolved after exiting the mutex:
+									return nil
+								end
+							end
+						end
+					ensure
+						# Decrement waiting count when done:
+						@waiting -= 1
+					end
+				end
+			end
+			
+			return @resolved
+		end
+		
 		# Wait for the promise to be resolved and return the value.
+		#
 		# If already resolved, returns immediately. If rejected, raises the stored exception.
 		#
 		# @returns [Object] The resolved value.
 		# @raises [Exception] The rejected or cancelled exception.
-		def wait
-			@mutex.synchronize do
-				# Increment waiting count:
-				@waiting += 1
-				
-				begin
-					# Wait for resolution if not already resolved:
-					until @resolved
-						@condition.wait(@mutex)
-					end
-					
-					# Return value or raise exception based on resolution type:
-					if @resolved == :completed
-						return @value
-					else
-						# Both :failed and :cancelled store exceptions in @value
-						raise @value
-					end
-				ensure
-					# Decrement waiting count when done:
-					@waiting -= 1
-				end
+		# @raises [Async::TimeoutError] If timeout expires before the promise is resolved.
+		def wait(...)
+			resolved = wait?(...)
+			
+			if resolved.nil?
+				raise TimeoutError, "Timeout while waiting for promise!"
+			elsif resolved == :completed
+				return @value
+			elsif @value
+				# If we aren't completed, we should have an exception or cancel reason stored:
+				raise @value
 			end
 		end
 		
@@ -113,8 +176,8 @@ module Async
 			@mutex.synchronize do
 				return if @resolved
 				
-				@value = value
 				@resolved = :completed
+				@value = value
 				
 				# Wake up all waiting fibers:
 				@condition.broadcast
@@ -132,8 +195,8 @@ module Async
 			@mutex.synchronize do
 				return if @resolved
 				
-				@value = exception
 				@resolved = :failed
+				@value = exception
 				
 				# Wake up all waiting fibers:
 				@condition.broadcast
@@ -142,20 +205,16 @@ module Async
 			return nil
 		end
 		
-		# Exception used to indicate cancellation.
-		class Cancel < Exception
-		end
-		
 		# Cancel the promise, indicating cancellation.
 		# All current and future waiters will receive nil.
 		# Can only be called on pending promises - no-op if already resolved.
-		def cancel(exception = Cancel.new("Promise was cancelled!"))
+		def cancel(exception = Cancel.new("Promise cancelled!"))
 			@mutex.synchronize do
 				# No-op if already in any final state
 				return if @resolved
 				
-				@value = exception
 				@resolved = :cancelled
+				@value = exception
 				
 				# Wake up all waiting fibers:
 				@condition.broadcast

data/lib/async/scheduler.rb

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2025, by Samuel Williams.
+# Copyright, 2020-2026, by Samuel Williams.
 # Copyright, 2020, by Jun Jiang.
 # Copyright, 2021, by Julien Portalier.
-# Copyright, 2025, by Shopify Inc.
+# Copyright, 2025-2026, by Shopify Inc.
 
 require_relative "clock"
 require_relative "task"
@@ -179,7 +179,7 @@ module Async
 		
 		# @returns [String] A description of the scheduler.
 		def to_s
-			"\#<#{self.description} #{@children&.size || 0} children (#{stopped? ? 'stopped' : 'running'})>"
+			"\#<#{self.description} #{@children&.size || 0} children (#{cancelled? ? 'cancelled' : 'running'})>"
 		end
 		
 		# Interrupt the event loop and cause it to exit.
@@ -511,15 +511,20 @@ module Async
 			return false
 		end
 		
-		# Stop all children, including transient children.
+		# Cancel all children, including transient children.
 		#
 		# @public Since *Async v1*.
-		def stop
+		def cancel
 			@children&.each do |child|
-				child.stop
+				child.cancel
 			end
 		end
 		
+		# Backward compatibility alias for cancel.
+		def stop
+			cancel
+		end
+		
 		private def run_loop(&block)
 			interrupt = nil
 			

data/lib/async/stop.rb

@@ -1,82 +1,10 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2025, by Samuel Williams.
+# Copyright, 2025-2026, by Samuel Williams.
 
-require "fiber"
-require "console"
+require_relative "cancel"
 
 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
+	Stop = Cancel
 end

data/lib/async/task.rb

@@ -1,37 +1,27 @@
 # 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, 2017, by Devin Christensen.
 # Copyright, 2020, by Patrik Wenger.
 # Copyright, 2023, by Math Ieu.
 # Copyright, 2025, by Shigeru Nakajima.
-# Copyright, 2025, by Shopify Inc.
+# Copyright, 2025-2026, by Shopify Inc.
 
 require "fiber"
 require "console"
 
 require_relative "node"
 require_relative "condition"
+require_relative "error"
 require_relative "promise"
 require_relative "stop"
 
 Fiber.attr_accessor :async_task
 
 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
-	
-	# Represents a sequential unit of work, defined by a block, which is executed concurrently with other tasks. A task can be in one of the following states: `initialized`, `running`, `completed`, `failed`, `cancelled` or `stopped`.
+	# Represents a sequential unit of work, defined by a block, which is executed concurrently with other tasks. A task can be in one of the following states: `initialized`, `running`, `completed`, `failed`, or `cancelled`.
 	#
 	# ```mermaid
 	# stateDiagram-v2
@@ -44,11 +34,11 @@ module Async
 	# Completed --> [*]
 	# Failed --> [*]
 	#
-	# Running --> Stopped : Stop
-	# Stopped --> [*]
-	# Completed --> Stopped : Stop
-	# Failed --> Stopped : Stop
-	# Initialized --> Stopped : Stop
+	# Running --> Cancelled : Cancel
+	# Cancelled --> [*]
+	# Completed --> Cancelled : Cancel
+	# Failed --> Cancelled : Cancel
+	# Initialized --> Cancelled : Cancel
 	# ```
 	#
 	# @example Creating a task that sleeps for 1 second.
@@ -108,7 +98,7 @@ module Async
 				warn("finished: argument with non-false value is deprecated and will be removed.", uplevel: 1, category: :deprecated) if $VERBOSE
 			end
 			
-			@defer_stop = nil
+			@defer_cancel = nil
 			
 			# Call this after all state is initialized, as it may call `add_child` which will set the parent and make it visible to the scheduler.
 			super(parent, **options)
@@ -193,8 +183,8 @@ module Async
 			@promise.failed?
 		end
 		
-		# @returns [Boolean] Whether the task has been stopped.
-		def stopped?
+		# @returns [Boolean] Whether the task has been cancelled.
+		def cancelled?
 			@promise.cancelled?
 		end
 		
@@ -208,11 +198,11 @@ module Async
 			self.completed?
 		end
 		
-		# @attribute [Symbol] The status of the execution of the task, one of `:initialized`, `:running`, `:complete`, `:stopped` or `:failed`.
+		# @attribute [Symbol] The status of the execution of the task, one of `:initialized`, `:running`, `:complete`, `:cancelled` or `:failed`.
 		def status
 			case @promise.resolved
 			when :cancelled
-				:stopped
+				:cancelled
 			when :failed
 				:failed
 			when :completed
@@ -270,23 +260,19 @@ module Async
 			return task
 		end
 		
-		# Retrieve the current result of the task. Will cause the caller to wait until result is available. If the task resulted in an unhandled error (derived from `StandardError`), this will be raised. If the task was stopped, this will return `nil`.
+		# Retrieve the current result of the task. Will cause the caller to wait until result is available. If the task resulted in an unhandled error (derived from `StandardError`), this will be raised. If the task was cancelled, this will return `nil`.
 		#
 		# Conceptually speaking, waiting on a task should return a result, and if it throws an exception, this is certainly an exceptional case that should represent a failure in your program, not an expected outcome. In other words, you should not design your programs to expect exceptions from `#wait` as a normal flow control, and prefer to catch known exceptions within the task itself and return a result that captures the intention of the failure, e.g. a `TimeoutError` might simply return `nil` or `false` to indicate that the operation did not generate a valid result (as a timeout was an expected outcome of the internal operation in this case).
 		#
+		# @parameter timeout [Numeric] The maximum number of seconds to wait for the result before raising a `TimeoutError`, if specified.
 		# @raises [RuntimeError] If the task's fiber is the current fiber.
 		# @returns [Object] The final expression/result of the task's block.
 		# @asynchronous This method is thread-safe.
-		def wait
+		def wait(...)
 			raise "Cannot wait on own fiber!" if Fiber.current.equal?(@fiber)
 			
-			# Wait for the task to complete - Promise handles all the complexity:
-			begin
-				@promise.wait
-			rescue Promise::Cancel
-				# For backward compatibility, stopped tasks return nil:
-				return nil
-			end
+			# Wait for the task to complete:
+			@promise.wait(...)
 		end
 		
 		# For compatibility with `Thread#join` and similar interfaces.
@@ -325,7 +311,7 @@ module Async
 		def result
 			value = @promise.value
 			
-			# For backward compatibility, return nil for stopped tasks:
+			# For backward compatibility, return nil for cancelled tasks:
 			if @promise.cancelled?
 				nil
 			else
@@ -333,103 +319,115 @@ module Async
 			end
 		end
 		
-		# Stop the task and all of its children.
+		# Cancel the task and all of its children.
 		#
-		# If `later` is false, it means that `stop` has been invoked directly. When `later` is true, it means that `stop` is invoked by `stop_children` or some other indirect mechanism. In that case, if we encounter the "current" fiber, we can't stop it right away, as it's currently performing `#stop`. Stopping it immediately would interrupt the current stop traversal, so we need to schedule the stop to occur later.
+		# If `later` is false, it means that `cancel` has been invoked directly. When `later` is true, it means that `cancel` is invoked by `stop_children` or some other indirect mechanism. In that case, if we encounter the "current" fiber, we can't cancel it right away, as it's currently performing `#cancel`. Cancelling it immediately would interrupt the current cancel traversal, so we need to schedule the cancel to occur later.
 		#
-		# @parameter later [Boolean] Whether to stop the task later, or immediately.
-		# @parameter cause [Exception] The cause of the stop operation.
-		def stop(later = false, cause: $!)
+		# @parameter later [Boolean] Whether to cancel the task later, or immediately.
+		# @parameter cause [Exception] The cause of the cancel operation.
+		def cancel(later = false, cause: $!)
 			# If no cause is given, we generate one from the current call stack:
 			unless cause
-				cause = Stop::Cause.for("Stopping task!")
+				cause = Cancel::Cause.for("Cancelling task!")
 			end
 			
-			if self.stopped?
-				# If the task is already stopped, a `stop` state transition re-enters the same state which is a no-op. However, we will also attempt to stop any running children too. This can happen if the children did not stop correctly the first time around. Doing this should probably be considered a bug, but it's better to be safe than sorry.
-				return stopped!
+			if self.cancelled?
+				# If the task is already cancelled, a `cancel` state transition re-enters the same state which is a no-op. However, we will also attempt to cancel any running children too. This can happen if the children did not cancel correctly the first time around. Doing this should probably be considered a bug, but it's better to be safe than sorry.
+				return cancelled!
 			end
 			
-			# If the fiber is alive, we need to stop it:
+			# If the fiber is alive, we need to cancel it:
 			if @fiber&.alive?
 				# As the task is now exiting, we want to ensure the event loop continues to execute until the task finishes.
 				self.transient = false
 				
-				# If we are deferring stop...
-				if @defer_stop == false
-					# Don't stop now... but update the state so we know we need to stop later.
-					@defer_stop = cause
+				# If we are deferring cancel...
+				if @defer_cancel == false
+					# Don't cancel now... but update the state so we know we need to cancel later.
+					@defer_cancel = cause
 					return false
 				end
 				
 				if self.current?
-					# If the fiber is current, and later is `true`, we need to schedule the fiber to be stopped later, as it's currently invoking `stop`:
+					# If the fiber is current, and later is `true`, we need to schedule the fiber to be cancelled later, as it's currently invoking `cancel`:
 					if later
-						# If the fiber is the current fiber and we want to stop it later, schedule it:
-						Fiber.scheduler.push(Stop::Later.new(self, cause))
+						# If the fiber is the current fiber and we want to cancel it later, schedule it:
+						Fiber.scheduler.push(Cancel::Later.new(self, cause))
 					else
 						# Otherwise, raise the exception directly:
-						raise Stop, "Stopping current task!", cause: cause
+						raise Cancel, "Cancelling current task!", cause: cause
 					end
 				else
 					# If the fiber is not curent, we can raise the exception directly:
 					begin
-						# There is a chance that this will stop the fiber that originally called stop. If that happens, the exception handling in `#stopped` will rescue the exception and re-raise it later.
-						Fiber.scheduler.raise(@fiber, Stop, cause: cause)
+						# There is a chance that this will cancel the fiber that originally called cancel. If that happens, the exception handling in `#cancelled` will rescue the exception and re-raise it later.
+						Fiber.scheduler.raise(@fiber, Cancel, cause: cause)
 					rescue FiberError
-						# In some cases, this can cause a FiberError (it might be resumed already), so we schedule it to be stopped later:
-						Fiber.scheduler.push(Stop::Later.new(self, cause))
+						# In some cases, this can cause a FiberError (it might be resumed already), so we schedule it to be cancelled later:
+						Fiber.scheduler.push(Cancel::Later.new(self, cause))
 					end
 				end
 			else
-				# We are not running, but children might be, so transition directly into stopped state:
-				stop!
+				# We are not running, but children might be, so transition directly into cancelled state:
+				cancel!
 			end
 		end
 		
-		# Defer the handling of stop. During the execution of the given block, if a stop is requested, it will be deferred until the block exits. This is useful for ensuring graceful shutdown of servers and other long-running tasks. You should wrap the response handling code in a defer_stop block to ensure that the task is stopped when the response is complete but not before.
+		# Defer the handling of cancel. During the execution of the given block, if a cancel is requested, it will be deferred until the block exits. This is useful for ensuring graceful shutdown of servers and other long-running tasks. You should wrap the response handling code in a defer_cancel block to ensure that the task is cancelled when the response is complete but not before.
 		#
-		# You can nest calls to defer_stop, but the stop will only be deferred until the outermost block exits.
+		# You can nest calls to defer_cancel, but the cancel will only be deferred until the outermost block exits.
 		#
-		# If stop is invoked a second time, it will be immediately executed.
+		# If cancel is invoked a second time, it will be immediately executed.
 		#
 		# @yields {} The block of code to execute.
 		# @public Since *Async v1*.
-		def defer_stop
-			# Tri-state variable for controlling stop:
-			# - nil: defer_stop has not been called.
-			# - false: defer_stop has been called and we are not stopping.
-			# - true: defer_stop has been called and we will stop when exiting the block.
-			if @defer_stop.nil?
+		def defer_cancel
+			# Tri-state variable for controlling cancel:
+			# - nil: defer_cancel has not been called.
+			# - false: defer_cancel has been called and we are not cancelling.
+			# - true: defer_cancel has been called and we will cancel when exiting the block.
+			if @defer_cancel.nil?
 				begin
-					# If we are not deferring stop already, we can defer it now:
-					@defer_stop = false
+					# If we are not deferring cancel already, we can defer it now:
+					@defer_cancel = false
 					
 					yield
-				rescue Stop
-					# If we are exiting due to a stop, we shouldn't try to invoke stop again:
-					@defer_stop = nil
+				rescue Cancel
+					# If we are exiting due to a cancel, we shouldn't try to invoke cancel again:
+					@defer_cancel = nil
 					raise
 				ensure
-					defer_stop = @defer_stop
+					defer_cancel = @defer_cancel
 					
 					# We need to ensure the state is reset before we exit the block:
-					@defer_stop = nil
+					@defer_cancel = nil
 					
-					# If we were asked to stop, we should do so now:
-					if defer_stop
-						raise Stop, "Stopping current task (was deferred)!", cause: defer_stop
+					# If we were asked to cancel, we should do so now:
+					if defer_cancel
+						raise Cancel, "Cancelling current task (was deferred)!", cause: defer_cancel
 					end
 				end
 			else
-				# If we are deferring stop already, entering it again is a no-op.
+				# If we are deferring cancel already, entering it again is a no-op.
 				yield
 			end
 		end
 		
-		# @returns [Boolean] Whether stop has been deferred.
+		# Backward compatibility alias for {#defer_cancel}.
+		# @deprecated Use {#defer_cancel} instead.
+		def defer_stop(&block)
+			defer_cancel(&block)
+		end
+		
+		# @returns [Boolean] Whether cancel has been deferred.
+		def cancel_deferred?
+			!!@defer_cancel
+		end
+		
+		# Backward compatibility alias for {#cancel_deferred?}.
+		# @deprecated Use {#cancel_deferred?} instead.
 		def stop_deferred?
-			!!@defer_stop
+			cancel_deferred?
 		end
 		
 		# Lookup the {Task} for the current fiber. Raise `RuntimeError` if none is available.
@@ -478,40 +476,48 @@ module Async
 			@promise.reject(exception)
 		end
 		
-		def stopped!
-			# Console.info(self, status:) {"Task #{self} was stopped with #{@children&.size.inspect} children!"}
+		def cancelled!
+			# Console.info(self, status:) {"Task #{self} was cancelled with #{@children&.size.inspect} children!"}
 			
-			# Cancel the promise:
-			@promise.cancel
+			# Cancel the promise, specify nil here so that no exception is raised when waiting on the promise:
+			@promise.cancel(nil)
 			
-			stopped = false
+			cancelled = false
 			
 			begin
 				# We are not running, but children might be so we should stop them:
 				stop_children(true)
-			rescue Stop
-				stopped = true
-				# If we are stopping children, and one of them tries to stop the current task, we should ignore it. We will be stopped later.
+			rescue Cancel
+				cancelled = true
+				# If we are cancelling children, and one of them tries to cancel the current task, we should ignore it. We will be cancelled later.
 				retry
 			end
 			
-			if stopped
-				raise Stop, "Stopping current task!"
+			if cancelled
+				raise Cancel, "Cancelling current task!"
 			end
 		end
 		
-		def stop!
-			stopped!
+		def stopped!
+			cancelled!
+		end
+		
+		def cancel!
+			cancelled!
 			
 			finish!
 		end
 		
+		def stop!
+			cancel!
+		end
+		
 		def schedule(&block)
 			@fiber = Fiber.new(annotation: self.annotation) do
 				begin
 					completed!(yield)
-				rescue Stop
-					stopped!
+				rescue Cancel
+					cancelled!
 				rescue StandardError => error
 					failed!(error)
 				rescue Exception => exception

data/lib/async/version.rb

@@ -1,8 +1,9 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2017-2025, by Samuel Williams.
+# Copyright, 2017-2026, by Samuel Williams.
 
+# @namespace
 module Async
-	VERSION = "2.36.0"
+	VERSION = "2.38.0"
 end

data/lib/async.rb

@@ -1,16 +1,13 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2017-2025, by Samuel Williams.
+# Copyright, 2017-2026, by Samuel Williams.
 # Copyright, 2020, by Salim Semaoune.
 
 require_relative "async/version"
 require_relative "async/reactor"
+require_relative "async/loop"
 
 require_relative "kernel/async"
 require_relative "kernel/sync"
 require_relative "kernel/barrier"
-
-# Asynchronous programming framework.
-module Async
-end

data/license.md

@@ -31,7 +31,7 @@ Copyright, 2025, by Jahfer Husain.
 Copyright, 2025, by Mark Montroy.  
 Copyright, 2025, by Shigeru Nakajima.  
 Copyright, 2025, by Alan Wu.  
-Copyright, 2025, by Shopify Inc.  
+Copyright, 2025-2026, by Shopify Inc.  
 Copyright, 2025, by Josh Teeter.  
 Copyright, 2025, by Jatin Goyal.  
 Copyright, 2025, by Yuhi Sato.  

data/readme.md

@@ -35,6 +35,16 @@ Please see the [project documentation](https://socketry.github.io/async/) for mo
 
 Please see the [project releases](https://socketry.github.io/async/releases/index) for all releases.
 
+### v2.38.0
+
+  - Rename `Task#stop` to `Task#cancel` for better clarity and consistency with common concurrency terminology. The old `stop` method is still available as an alias for backward compatibility, but it is recommended to use `cancel` going forward.
+  - Forward arguments from `Task#wait` -\> `Promise#wait`, so `task.wait(timeout: N)` is supported.
+
+### v2.37.0
+
+  - Introduce `Async::Loop` for robust, time-aligned loops.
+  - Add support for `Async::Promise#wait(timeout: N)`.
+
 ### v2.36.0
 
   - Introduce `Task#wait_all` which recursively waits for all children and self, excepting the current task.
@@ -69,14 +79,6 @@ Please see the [project releases](https://socketry.github.io/async/releases/inde
 
   - Fix typo in documentation.
 
-### v2.32.0
-
-  - Introduce `Queue#waiting_count` and `PriorityQueue#waiting_count`. Generally for statistics/testing purposes only.
-
-### v2.31.0
-
-  - Introduce `Async::Deadline` for precise timeout management in compound operations.
-
 ## See Also
 
   - [async-http](https://github.com/socketry/async-http) — Asynchronous HTTP client/server.

data/releases.md

@@ -1,5 +1,15 @@
 # Releases
 
+## v2.38.0
+
+  - Rename `Task#stop` to `Task#cancel` for better clarity and consistency with common concurrency terminology. The old `stop` method is still available as an alias for backward compatibility, but it is recommended to use `cancel` going forward.
+  - Forward arguments from `Task#wait` -\> `Promise#wait`, so `task.wait(timeout: N)` is supported.
+
+## v2.37.0
+
+  - Introduce `Async::Loop` for robust, time-aligned loops.
+  - Add support for `Async::Promise#wait(timeout: N)`.
+
 ## v2.36.0
 
   - Introduce `Task#wait_all` which recursively waits for all children and self, excepting the current task.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async
 version: !ruby/object:Gem::Version
-  version: 2.36.0
+  version: 2.38.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -156,15 +156,18 @@ files:
 - lib/async.rb
 - lib/async/barrier.md
 - lib/async/barrier.rb
+- lib/async/cancel.rb
 - lib/async/clock.rb
 - lib/async/condition.md
 - lib/async/condition.rb
 - lib/async/console.rb
 - lib/async/deadline.rb
+- lib/async/error.rb
 - lib/async/fork_handler.rb
 - lib/async/idler.rb
 - lib/async/limited_queue.rb
 - lib/async/list.rb
+- lib/async/loop.rb
 - lib/async/node.rb
 - lib/async/notification.rb
 - lib/async/priority_queue.rb
@@ -205,7 +208,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.2'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="