Add support for Async::Promise#wait(timeout: N). (#446)

Author: ioquatix

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

lib/async/promise.rb

@@ -4,6 +4,9 @@
 # Copyright, 2025, by Shopify Inc.
 # Copyright, 2025-2026, by Samuel Williams.
 
+require_relative "error"
+require_relative "deadline"
+
 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 
@@ -77,17 +80,23 @@ def value
 		# Wait for the promise to be resolved and return the value.
 		# If already resolved, returns immediately. If rejected, raises the stored exception.
 		#
+		# @parameter timeout [Numeric | Nil] Maximum time to wait. If nil, waits indefinitely. If 0, raises immediately if not resolved.
 		# @returns [Object] The resolved value.
 		# @raises [Exception] The rejected or cancelled exception.
-		def wait
+		# @raises [Async::TimeoutError] If timeout expires before the promise is resolved.
+		def wait(timeout: nil)
 			@mutex.synchronize do
 				# Increment waiting count:
 				@waiting += 1
 
 				begin
 					# Wait for resolution if not already resolved:
-					until @resolved
-						@condition.wait(@mutex)
+					unless @resolved
+						if timeout.nil?
+							wait_indefinitely
+						else
+							wait_with_timeout(timeout)
+						end
 					end
 
 					# Return value or raise exception based on resolution type:
@@ -104,6 +113,39 @@ def wait
 			end
 		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.
+		# @raises [Async::TimeoutError] If the timeout expires before resolution.
+		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
+				raise Async::TimeoutError, "Promise wait not resolved!"
+			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
+					raise Async::TimeoutError, "Promise wait timed out!"
+				end
+				
+				@condition.wait(@mutex, remaining)
+			end
+		end
+		
 		# Resolve the promise with a value.
 		# All current and future waiters will receive this value.
 		# Can only be called once - subsequent calls are ignored.

lib/async/task.rb

@@ -14,23 +14,13 @@
 
 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`.
 	#
 	# ```mermaid

test/async/promise.rb

@@ -187,6 +187,130 @@
 			expect(errors).to be(:all?){|error| error == test_error}
 			expect(promise.waiting?).to be == false
 		end
+		
+		it "returns immediately when already resolved with timeout" do
+			promise.resolve(:immediate)
+			
+			# Should return immediately even with timeout:
+			expect(promise.wait(timeout: 0.1)).to be == :immediate
+			expect(promise.wait(timeout: 0)).to be == :immediate
+		end
+		
+		it "raises TimeoutError with timeout: 0 if not resolved" do
+			error = nil
+			
+			expect do
+				promise.wait(timeout: 0)
+			end.to raise_exception(Async::TimeoutError, message: be =~ /not resolved/)
+		end
+		
+		it "raises TimeoutError after timeout expires" do
+			error = nil
+			start_time = Time.now
+			
+			waiter = reactor.async do
+				begin
+					promise.wait(timeout: 0.1)
+				rescue Async::TimeoutError => error
+				end
+			end
+			
+			# Waiter should be waiting:
+			expect(promise).to be(:waiting?)
+			
+			# Wait for timeout:
+			waiter.wait
+			elapsed = Time.now - start_time
+			
+			expect(error).to be_a(Async::TimeoutError)
+			expect(error.message).to be =~ /timed out/
+			expect(elapsed).to be >= 0.1
+			expect(elapsed).to be < 0.5
+			expect(promise).not.to be(:waiting?)
+		end
+		
+		it "returns value before timeout expires" do
+			result = nil
+			
+			waiter = reactor.async do
+				result = promise.wait(timeout: 1.0)
+			end
+			
+			# Waiter should be waiting:
+			expect(promise).to be(:waiting?)
+			
+			# Resolve quickly (before timeout):
+			reactor.sleep(0.05)
+			promise.resolve(:quick_result)
+			waiter.wait
+			
+			expect(result).to be == :quick_result
+			expect(promise).not.to be(:waiting?)
+		end
+		
+		it "handles timeout with multiple concurrent waiters" do
+			results = []
+			errors = []
+			
+			# Start multiple waiters with timeout:
+			waiters = 3.times.map do |i|
+				reactor.async do
+					begin
+						results << promise.wait(timeout: 0.1)
+					rescue Async::TimeoutError => error
+						errors << error
+					end
+				end
+			end
+			
+			# All should be waiting:
+			expect(promise).to be(:waiting?)
+			
+			# Wait for all to timeout:
+			waiters.each(&:wait)
+			
+			expect(results).to be(:empty?)
+			expect(errors.size).to be == 3
+			expect(errors).to be(:all?){|error| error.is_a?(Async::TimeoutError)}
+			expect(promise).not.to be(:waiting?)
+		end
+		
+		it "handles timeout where some waiters succeed and others timeout" do
+			results = []
+			errors = []
+			
+			# Start waiters with different timeouts:
+			waiters = [
+				reactor.async do
+					begin
+						results << promise.wait(timeout: 0.05)
+					rescue Async::TimeoutError => error
+						errors << error
+					end
+				end,
+				reactor.async do
+					begin
+						results << promise.wait(timeout: 0.2)
+					rescue Async::TimeoutError => error
+						errors << error
+					end
+				end
+			]
+			
+			# All should be waiting:
+			expect(promise).to be(:waiting?)
+			
+			# Resolve after first timeout but before second:
+			sleep(0.1)
+			promise.resolve(:partial_success)
+			waiters.each(&:wait)
+			
+			# First waiter should have timed out, second should have succeeded:
+			expect(errors.size).to be == 1
+			expect(errors.first).to be_a(Async::TimeoutError)
+			expect(results).to be == [:partial_success]
+			expect(promise).not.to be(:waiting?)
+		end
 	end
 
 	with "warning suppression" do