async 2.17.0 → 2.32.0

data/lib/async/task.rb

@@ -1,46 +1,27 @@
 # 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, 2017, by Devin Christensen.
 # Copyright, 2020, by Patrik Wenger.
 # Copyright, 2023, by Math Ieu.
+# Copyright, 2025, by Shigeru Nakajima.
+# Copyright, 2025, by Shopify Inc.
 
-require 'fiber'
-require 'console/event/failure'
+require "fiber"
+require "console"
 
-require_relative 'node'
-require_relative 'condition'
+require_relative "node"
+require_relative "condition"
+require_relative "promise"
+require_relative "stop"
 
 Fiber.attr_accessor :async_task
 
 module Async
-	# Raised when a task is explicitly stopped.
-	class Stop < Exception
-		# 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.
-			def initialize(task)
-				@task = task
-			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
-			end
-		end
-	end
-	
 	# Raised if a timeout occurs on a specific Fiber. Handled gracefully by `Task`.
-	# @public Since `stable-v1`.
+	# @public Since *Async v1*.
 	class TimeoutError < StandardError
 		# Create a new timeout error.
 		#
@@ -50,7 +31,7 @@ module Async
 		end
 	end
 	
-	# @public Since `stable-v1`.
+	# @public Since *Async v1*.
 	class Task < Node
 		# Raised when a child task is created within a task that has finished execution.
 		class FinishedError < RuntimeError
@@ -64,6 +45,8 @@ module Async
 		
 		# @deprecated With no replacement.
 		def self.yield
+			warn("`Async::Task.yield` is deprecated with no replacement.", uplevel: 1, category: :deprecated) if $VERBOSE
+			
 			Fiber.scheduler.transfer
 		end
 		
@@ -82,14 +65,24 @@ module Async
 			
 			# These instance variables are critical to the state of the task.
 			# In the initialized state, the @block should be set, but the @fiber should be nil.
-			# In the running state, the @fiber should be set.
+			# In the running state, the @fiber should be set, and @block should be nil.
 			# In a finished state, the @block should be nil, and the @fiber should be nil.
 			@block = block
 			@fiber = nil
 			
-			@status = :initialized
-			@result = nil
-			@finished = finished
+			@promise = Promise.new
+			
+			# Handle finished: parameter for backward compatibility:
+			case finished
+			when false
+				# `finished: false` suppresses warnings for expected task failures:
+				@promise.suppress_warnings!
+			when nil
+				# `finished: nil` is the default, no special handling:
+			else
+				# All other `finished:` values are deprecated:
+				warn("finished: argument with non-false value is deprecated and will be removed.", uplevel: 1, category: :deprecated) if $VERBOSE
+			end
 			
 			@defer_stop = nil
 		end
@@ -128,11 +121,13 @@ module Async
 		
 		# @returns [String] A description of the task and it's current status.
 		def to_s
-			"\#<#{self.description} (#{@status})>"
+			"\#<#{self.description} (#{self.status})>"
 		end
 		
 		# @deprecated Prefer {Kernel#sleep} except when compatibility with `stable-v1` is required.
 		def sleep(duration = nil)
+			Kernel.warn("`Async::Task#sleep` is deprecated, use `Kernel#sleep` instead.", uplevel: 1, category: :deprecated) if $VERBOSE
+			
 			super
 		end
 		
@@ -163,44 +158,57 @@ module Async
 		
 		# @returns [Boolean] Whether the task is running.
 		def running?
-			@status == :running
+			self.alive?
 		end
 		
 		# @returns [Boolean] Whether the task failed with an exception.
 		def failed?
-			@status == :failed
+			@promise.failed?
 		end
 		
 		# @returns [Boolean] Whether the task has been stopped.
 		def stopped?
-			@status == :stopped
+			@promise.cancelled?
 		end
 		
 		# @returns [Boolean] Whether the task has completed execution and generated a result.
 		def completed?
-			@status == :completed
+			@promise.completed?
 		end
 		
-		alias complete? completed?
+		# Alias for {#completed?}.
+		def complete?
+			self.completed?
+		end
 		
 		# @attribute [Symbol] The status of the execution of the task, one of `:initialized`, `:running`, `:complete`, `:stopped` or `:failed`.
-		attr :status
+		def status
+			case @promise.resolved
+			when :cancelled
+				:stopped
+			when :failed
+				:failed
+			when :completed
+				:completed
+			when nil
+				self.running? ? :running : :initialized
+			end
+		end
 		
 		# Begin the execution of the task.
 		#
 		# @raises [RuntimeError] If the task is already running.
 		def run(*arguments)
-			if @status == :initialized
-				@status = :running
+			# Move from initialized to running by clearing @block
+			if block = @block
+				@block = nil
 				
 				schedule do
-					@block.call(self, *arguments)
+					block.call(self, *arguments)
 				rescue => error
 					# I'm not completely happy with this overhead, but the alternative is to not log anything which makes debugging extremely difficult. Maybe we can introduce a debug wrapper which adds extra logging.
-					if @finished.nil?
-						Console::Event::Failure.for(error).emit(self, "Task may have ended with unhandled exception.", severity: :warn)
-					else
-						# Console::Event::Failure.for(error).emit(self, severity: :debug)
+					unless @promise.waiting?
+						warn(self, "Task may have ended with unhandled exception.", exception: error)
 					end
 					
 					raise
@@ -212,6 +220,10 @@ module Async
 		
 		# Run an asynchronous task as a child of the current task.
 		#
+		# @public Since *Async v1*.
+		# @asynchronous May context switch immediately to the new task.
+		#
+		# @yields {|task| ...} in the context of the new task.
 		# @raises [FinishedError] If the task has already finished.
 		# @returns [Task] The child task.
 		def async(*arguments, **options, &block)
@@ -219,6 +231,13 @@ module Async
 			
 			task = Task.new(self, **options, &block)
 			
+			# When calling an async block, we deterministically execute it until the first blocking operation. We don't *have* to do this - we could schedule it for later execution, but it's useful to:
+			#
+			# - Fail at the point of the method call where possible.
+			# - Execute determinstically where possible.
+			# - Avoid scheduler overhead if no blocking operation is performed.
+			#
+			# There are different strategies (greedy vs non-greedy). We are currently using a greedy strategy.
 			task.run(*arguments)
 			
 			return task
@@ -230,31 +249,42 @@ module Async
 		#
 		# @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
 			raise "Cannot wait on own fiber!" if Fiber.current.equal?(@fiber)
 			
-			# `finish!` will set both of these to nil before signaling the condition:
-			if @block || @fiber
-				@finished ||= Condition.new
-				@finished.wait
-			end
-			
-			if @status == :failed
-				raise @result
-			else
-				return @result
+			# 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
 		end
 		
 		# Access the result of the task without waiting. May be nil if the task is not completed. Does not raise exceptions.
-		attr :result
+		def result
+			value = @promise.value
+			# For backward compatibility, return nil for stopped tasks
+			if @promise.cancelled?
+				nil
+			else
+				value
+			end
+		end
 		
 		# Stop 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.
 		#
 		# @parameter later [Boolean] Whether to stop the task later, or immediately.
-		def stop(later = false)
+		# @parameter cause [Exception] The cause of the stop operation.
+		def stop(later = false, cause: $!)
+			# If no cause is given, we generate one from the current call stack:
+			unless cause
+				cause = Stop::Cause.for("Stopping 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!
@@ -268,7 +298,7 @@ module Async
 				# 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 = true
+					@defer_stop = cause
 					return false
 				end
 				
@@ -276,19 +306,19 @@ module Async
 					# 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 later
 						# If the fiber is the current fiber and we want to stop it later, schedule it:
-						Fiber.scheduler.push(Stop::Later.new(self))
+						Fiber.scheduler.push(Stop::Later.new(self, cause))
 					else
 						# Otherwise, raise the exception directly:
-						raise Stop, "Stopping current task!"
+						raise Stop, "Stopping 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)
-					rescue FiberError => error
+						Fiber.scheduler.raise(@fiber, Stop, 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))
+						Fiber.scheduler.push(Stop::Later.new(self, cause))
 					end
 				end
 			else
@@ -304,7 +334,7 @@ module Async
 		# If stop is invoked a second time, it will be immediately executed.
 		#
 		# @yields {} The block of code to execute.
-		# @public Since `stable-v1`.
+		# @public Since *Async v1*.
 		def defer_stop
 			# Tri-state variable for controlling stop:
 			# - nil: defer_stop has not been called.
@@ -328,7 +358,7 @@ module Async
 					
 					# If we were asked to stop, we should do so now:
 					if defer_stop
-						raise Stop, "Stopping current task (was deferred)!"
+						raise Stop, "Stopping current task (was deferred)!", cause: defer_stop
 					end
 				end
 			else
@@ -339,7 +369,7 @@ module Async
 		
 		# @returns [Boolean] Whether stop has been deferred.
 		def stop_deferred?
-			@defer_stop
+			!!@defer_stop
 		end
 		
 		# Lookup the {Task} for the current fiber. Raise `RuntimeError` if none is available.
@@ -362,6 +392,10 @@ module Async
 		
 		private
 		
+		def warn(...)
+			Console.warn(...)
+		end
+		
 		# Finish the current task, moving any children to the parent.
 		def finish!
 			# Don't hold references to the fiber or block after the task has finished:
@@ -370,29 +404,25 @@ module Async
 			
 			# Attempt to remove this node from the task tree.
 			consume
-			
-			# If this task was being used as a future, signal completion here:
-			if @finished
-				@finished.signal(self)
-				@finished = nil
-			end
 		end
 		
 		# State transition into the completed state.
 		def completed!(result)
-			@result = result
-			@status = :completed
+			# Resolve the promise with the result:
+			@promise&.resolve(result)
 		end
 		
 		# State transition into the failed state.
 		def failed!(exception = false)
-			@result = exception
-			@status = :failed
+			# Reject the promise with the exception:
+			@promise&.reject(exception)
 		end
 		
 		def stopped!
 			# Console.info(self, status:) {"Task #{self} was stopped with #{@children&.size.inspect} children!"}
-			@status = :stopped
+			
+			# Cancel the promise:
+			@promise&.cancel
 			
 			stopped = false
 			
@@ -437,7 +467,7 @@ module Async
 			
 			@fiber.async_task = self
 			
-			self.root.resume(@fiber)
+			(Fiber.scheduler || self.reactor).resume(@fiber)
 		end
 	end
 end

data/lib/async/timeout.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+module Async
+	# Represents a flexible timeout that can be rescheduled or extended.
+	# @public Since *Async v2.24*.
+	class Timeout
+		# Initialize a new timeout.
+		def initialize(timers, handle)
+			@timers = timers
+			@handle = handle
+		end
+		
+		# @returns [Numeric] The time remaining until the timeout occurs, in seconds.
+		def duration
+			@handle.time - @timers.now
+		end
+		
+		# Update the duration of the timeout.
+		#
+		# The duration is relative to the current time, e.g. setting the duration to 5 means the timeout will occur in 5 seconds from now.
+		#
+		# @parameter value [Numeric] The new duration to assign to the timeout, in seconds.
+		def duration=(value)
+			self.reschedule(@timers.now + value)
+		end
+		
+		# Adjust the timeout by the specified duration.
+		#
+		# The duration is relative to the timeout time, e.g. adjusting the timeout by 5 increases the current duration by 5 seconds.
+		#
+		# @parameter duration [Numeric] The duration to adjust the timeout by, in seconds.
+		# @returns [Numeric] The new time at which the timeout will occur.
+		def adjust(duration)
+			self.reschedule(time + duration)
+		end
+		
+		# @returns [Numeric] The time at which the timeout will occur, in seconds since {now}.
+		def time
+			@handle.time
+		end
+		
+		# Assign a new time to the timeout, rescheduling it if necessary.
+		#
+		# @parameter value [Numeric] The new time to assign to the timeout.
+		# @returns [Numeric] The new time at which the timeout will occur.
+		def time=(value)
+			self.reschedule(value)
+		end
+		
+		# @returns [Numeric] The current time in the scheduler, relative to the time of this timeout, in seconds.
+		def now
+			@timers.now
+		end
+		
+		# Cancel the timeout, preventing it from executing.
+		def cancel!
+			@handle.cancel!
+		end
+		
+		# @returns [Boolean] Whether the timeout has been cancelled.
+		def cancelled?
+			@handle.cancelled?
+		end
+		
+		# Raised when attempting to reschedule a cancelled timeout.
+		class CancelledError < RuntimeError
+		end
+		
+		# Reschedule the timeout to occur at the specified time.
+		#
+		# @parameter time [Numeric] The new time to schedule the timeout for.
+		# @returns [Numeric] The new time at which the timeout will occur.
+		private def reschedule(time)
+			if block = @handle&.block
+				@handle.cancel!
+				
+				@handle = @timers.schedule(time, block)
+				
+				return time
+			else
+				raise CancelledError, "Cannot reschedule a cancelled timeout!"
+			end
+		end
+	end
+end

data/lib/async/variable.rb

@@ -1,17 +1,22 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2021-2024, by Samuel Williams.
+# Copyright, 2021-2025, by Samuel Williams.
+# Copyright, 2025, by Shopify Inc.
 
-require_relative 'condition'
+require_relative "condition"
 
 module Async
 	# A synchronization primitive that allows one task to wait for another task to resolve a value.
+	#
+	# @deprecated Use {Async::Promise} instead.
 	class Variable
 		# Create a new variable.
 		#
 		# @parameter condition [Condition] The condition to use for synchronization.
 		def initialize(condition = Condition.new)
+			warn("`Async::Variable` is deprecated, use `Async::Promise` instead.", category: :deprecated, uplevel: 1) if $VERBOSE
+			
 			@condition = condition
 			@value = nil
 		end
@@ -31,7 +36,10 @@ module Async
 			condition.signal(value)
 		end
 		
-		alias value= resolve
+		# Alias for {#resolve}.
+		def value=(value)
+			self.resolve(value)
+		end
 		
 		# Whether the value has been resolved.
 		#
@@ -48,6 +56,9 @@ module Async
 			return @value
 		end
 		
-		alias value wait
+		# Alias for {#wait}.
+		def value
+			self.wait
+		end
 	end
 end

data/lib/async/version.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2017-2024, by Samuel Williams.
+# Copyright, 2017-2025, by Samuel Williams.
 
 module Async
-	VERSION = "2.17.0"
+	VERSION = "2.32.0"
 end

data/lib/async/waiter.rb

@@ -1,17 +1,22 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2022-2024, by Samuel Williams.
+# Copyright, 2022-2025, by Samuel Williams.
 # Copyright, 2024, by Patrik Wenger.
+# Copyright, 2025, by Shopify Inc.
 
 module Async
 	# A composable synchronization primitive, which allows one task to wait for a number of other tasks to complete. It can be used in conjunction with {Semaphore} and/or {Barrier}.
+	#
+	# @deprecated `Async::Waiter` is deprecated, use `Async::Barrier` instead. 
 	class Waiter
 		# Create a waiter instance.
 		#
 		# @parameter parent [Interface(:async) | Nil] The parent task to use for asynchronous operations.
 		# @parameter finished [Async::Condition] The condition to signal when a task completes.
 		def initialize(parent: nil, finished: Async::Condition.new)
+			warn("`Async::Waiter` is deprecated, use `Async::Barrier` instead.", uplevel: 1, category: :deprecated) if $VERBOSE
+			
 			@finished = finished
 			@done = []
 			

data/lib/kernel/async.rb

@@ -19,7 +19,7 @@ module Kernel
 	# @yields {|task| ...} The block that will execute asynchronously.
 	# 	@parameter task [Async::Task] The task that is executing the given block.
 	#
-	# @public Since `stable-v1`.
+	# @public Since *Async v1*.
 	# @asynchronous May block until given block completes executing.
 	def Async(...)
 		if current = ::Async::Task.current?

data/lib/kernel/sync.rb

@@ -1,8 +1,10 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2024, by Samuel Williams.
+# Copyright, 2019-2025, by Samuel Williams.
 # Copyright, 2020, by Brian Morearty.
+# Copyright, 2024, by Patrik Wenger.
+# Copyright, 2025, by Shopify Inc.
 
 require_relative "../async/reactor"
 
@@ -13,11 +15,15 @@ module Kernel
 	# @yields {|task| ...} The block that will execute asynchronously.
 	# 	@parameter task [Async::Task] The task that is executing the given block.
 	#
-	# @public Since `stable-v1`.
+	# @public Since *Async v1*.
 	# @asynchronous Will block until given block completes executing.
-	def Sync(&block)
+	def Sync(annotation: nil, &block)
 		if task = ::Async::Task.current?
-			yield task
+			if annotation
+				task.annotate(annotation) {yield task}
+			else
+				yield task
+			end
 		elsif scheduler = Fiber.scheduler
 			::Async::Task.run(scheduler, &block).wait
 		else
@@ -25,7 +31,10 @@ module Kernel
 			reactor = Async::Reactor.new
 			
 			begin
-				return reactor.run(finished: ::Async::Condition.new, &block).wait
+				# Use finished: false to suppress warnings since we're handling exceptions explicitly
+				task = reactor.async(annotation: annotation, finished: false, &block)
+				reactor.run
+				return task.wait
 			ensure
 				Fiber.set_scheduler(nil)
 			end

data/lib/metrics/provider/async/task.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2024-2025, by Samuel Williams.
+
+require_relative "../../../async/task"
+require "metrics/provider"
+
+Metrics::Provider(Async::Task) do
+	ASYNC_TASK_SCHEDULED = Metrics.metric("async.task.scheduled", :counter, description: "The number of tasks scheduled.")
+	ASYNC_TASK_FINISHED = Metrics.metric("async.task.finished", :counter, description: "The number of tasks finished.")
+	
+	def schedule(&block)
+		ASYNC_TASK_SCHEDULED.emit(1)
+		
+		super(&block)
+	ensure
+		ASYNC_TASK_FINISHED.emit(1)
+	end
+end

data/lib/metrics/provider/async.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2024, by Samuel Williams.
+
+require_relative "async/task"

data/lib/traces/provider/async/barrier.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2024-2025, by Samuel Williams.
+
+require_relative "../../../async/barrier"
+require "traces/provider"
+
+Traces::Provider(Async::Barrier) do
+	def wait
+		attributes = {
+			"size" => self.size
+		}
+		
+		Traces.trace("async.barrier.wait", attributes: attributes) {super}
+	end
+end