async 2.32.0 → 2.39.0

data/lib/async/promise.rb

@@ -2,7 +2,11 @@
 
 # Released under the MIT License.
 # Copyright, 2025, by Shopify Inc.
-# Copyright, 2025, by Samuel Williams.
+# 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.
@@ -30,39 +34,39 @@ module Async
 		
 		# @returns [Boolean] Whether the promise has been resolved or rejected.
 		def resolved?
-			@mutex.synchronize {!!@resolved}
+			@mutex.synchronize{!!@resolved}
 		end
 		
 		# @returns [Symbol | Nil] The internal resolved state (:completed, :failed, :cancelled, or nil if pending).
 		# @private For internal use by Task.
 		def resolved
-			@mutex.synchronize {@resolved}
+			@mutex.synchronize{@resolved}
 		end
 		
 		# @returns [Boolean] Whether the promise has been cancelled.
 		def cancelled?
-			@mutex.synchronize {@resolved == :cancelled}
+			@mutex.synchronize{@resolved == :cancelled}
 		end
 		
 		# @returns [Boolean] Whether the promise failed with an exception.
 		def failed?
-			@mutex.synchronize {@resolved == :failed}
+			@mutex.synchronize{@resolved == :failed}
 		end
 		
 		# @returns [Boolean] Whether the promise has completed successfully.
 		def completed?
-			@mutex.synchronize {@resolved == :completed}
+			@mutex.synchronize{@resolved == :completed}
 		end
 		
 		# @returns [Boolean] Whether any fibers are currently waiting for this promise.
 		def waiting?
-			@mutex.synchronize {@waiting > 0}
+			@mutex.synchronize{@waiting > 0}
 		end
 		
 		# Artificially mark that someone is waiting (useful for suppressing warnings).
 		# @private Internal use only.
 		def suppress_warnings!
-			@mutex.synchronize {@waiting += 1}
+			@mutex.synchronize{@waiting += 1}
 		end
 		
 		# Non-blocking access to the current value. Returns nil if not yet resolved.
@@ -71,34 +75,95 @@ module Async
 		#
 		# @returns [Object | Nil] The stored value, or nil if pending.
 		def value
-			@mutex.synchronize {@resolved ? @value : nil}
+			@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:
-					@condition.wait(@mutex) unless @resolved
-					
-					# 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
 		
@@ -111,8 +176,8 @@ module Async
 			@mutex.synchronize do
 				return if @resolved
 				
-				@value = value
 				@resolved = :completed
+				@value = value
 				
 				# Wake up all waiting fibers:
 				@condition.broadcast
@@ -130,8 +195,8 @@ module Async
 			@mutex.synchronize do
 				return if @resolved
 				
-				@value = exception
 				@resolved = :failed
+				@value = exception
 				
 				# Wake up all waiting fibers:
 				@condition.broadcast
@@ -140,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
@@ -184,5 +245,19 @@ module Async
 				self.resolve(nil) unless @resolved
 			end
 		end
+		
+		# If a promise is given, fulfill it with the result of the block.
+		# If no promise is given, simply yield to the block.
+		# This is useful for methods that may optionally take a promise to fulfill.
+		# @parameter promise [Promise | Nil] The optional promise to fulfill.
+		# @yields {...} The block to call to resolve the promise or return a value.
+		# @returns [Object] The result of the block.
+		def self.fulfill(promise, &block)
+			if promise
+				return promise.fulfill(&block)
+			else
+				return yield
+			end
+		end
 	end
 end

data/lib/async/queue.rb

@@ -72,7 +72,7 @@ module Async
 		
 		# Add multiple items to the queue.
 		def enqueue(*items)
-			items.each {|item| @delegate.push(item)}
+			items.each{|item| @delegate.push(item)}
 		rescue ClosedQueueError
 			raise ClosedError, "Cannot enqueue items to a closed queue!"
 		end

data/lib/async/scheduler.rb

@@ -1,14 +1,15 @@
 # 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"
 require_relative "timeout"
+require_relative "fork_handler"
 
 require "io/event"
 
@@ -146,24 +147,26 @@ module Async
 		# Terminate all child tasks and close the scheduler.
 		# @public Since *Async v1*.
 		def close
-			self.run_loop do
-				until self.terminate
-					self.run_once!
+			unless @children.nil?
+				self.run_loop do
+					until self.terminate
+						self.run_once!
+					end
 				end
 			end
 			
 			Kernel.raise "Closing scheduler with blocked operations!" if @blocked > 0
 		ensure
 			# We want `@selector = nil` to be a visible side effect from this point forward, specifically in `#interrupt` and `#unblock`. If the selector is closed, then we don't want to push any fibers to it.
-			selector = @selector
-			@selector = nil
-			
-			selector&.close
-			
-			worker_pool = @worker_pool
-			@worker_pool = nil
+			if selector = @selector
+				@selector = nil
+				selector.close
+			end
 			
-			worker_pool&.close
+			if worker_pool = @worker_pool
+				@worker_pool = nil
+				worker_pool.close
+			end
 			
 			consume
 		end
@@ -176,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.
@@ -508,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
 			
@@ -642,5 +650,20 @@ module Async
 				yield duration
 			end
 		end
+		
+		# Handle fork in the child process. This method is called automatically when `Process.fork` is invoked on Ruby versions < 4 and cleans up the scheduler state. On Ruby 4+, the scheduler is automatically cleaned up by the Ruby runtime.
+		#
+		# The child process starts with a clean slate - no scheduler is set. Users can create a new scheduler if needed.
+		#
+		# @public Since *Async v2.35*.
+		def process_fork
+			@profiler = nil
+			@children = nil
+			@selector = nil
+			@timers = nil
+			
+			# Close the scheduler:
+			Fiber.set_scheduler(nil)
+		end
 	end
 end

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