Add Async::Deadline for managing compound timeouts. (#421)

Author: samuel-williams-shopify

lib/async/deadline.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require_relative "clock"
+
+# @namespace
+module Async
+	# Represents a deadline timeout with decrementing remaining time.
+	# Includes an efficient representation for zero (non-blocking) timeouts.
+	# @public Since *Async v2.31*.
+	class Deadline
+		# Singleton module for immediate timeouts (zero or negative).
+		# Avoids object allocation for fast path (non-blocking) timeouts.
+		module Zero
+			# Check if the deadline has expired.
+			# @returns [Boolean] Always returns true since zero timeouts are immediately expired.
+			def self.expired?
+				true
+			end
+			
+			# Get the remaining time.
+			# @returns [Integer] Always returns 0 since zero timeouts have no remaining time.
+			def self.remaining
+				0
+			end
+		end
+		
+		# Create a deadline for the given timeout.
+		# @parameter timeout [Numeric | Nil] The timeout duration, or nil for no timeout.
+		# @returns [Deadline | Nil] A deadline instance, Zero singleton, or nil.
+		def self.start(timeout)
+			if timeout.nil?
+				nil
+			elsif timeout <= 0
+				Zero
+			else
+				self.new(timeout)
+			end
+		end
+		
+		# Create a new deadline with the specified remaining time.
+		# @parameter remaining [Numeric] The initial remaining time.
+		def initialize(remaining)
+			@remaining = remaining
+			@start = Clock.now
+		end
+		
+		# Get the remaining time, updating internal state.
+		# Each call to this method advances the internal clock and reduces
+		# the remaining time by the elapsed duration since the last call.
+		# @returns [Numeric] The remaining time (may be negative if expired).
+		def remaining
+			now = Clock.now
+			delta = now - @start
+			@start = now
+			
+			@remaining -= delta
+			
+			return @remaining
+		end
+		
+		# Check if the deadline has expired.
+		# @returns [Boolean] True if no time remains.
+		def expired?
+			self.remaining <= 0
+		end
+	end
+end

releases.md

@@ -1,5 +1,9 @@
 # Releases
 
+## Unreleased
+
+  - Introduce `Async::Deadline` for precise timeout management in compound operations.
+
 ## v2.30.0
 
   - Add timeout support to `Async::Queue#dequeue` and `Async::Queue#pop` methods.

test/async/clock.rb

@@ -31,6 +31,41 @@
 		expect(clock.total).to be_within(2 * Sus::Fixtures::Time::QUANTUM).of(0.02)
 	end
 
+	with "#start" do
+		it "handles multiple start/stop cycles" do
+			3.times do
+				clock.start!
+				# Calling start! again should be idempotent - no time should be added
+				first_total = clock.total
+				clock.start!
+				second_total = clock.total
+				
+				# The total should not jump significantly just from calling start! again
+				expect(second_total - first_total).to be < 0.001
+				clock.stop!
+			end
+			
+			expect(clock.total).to be >= 0
+		end
+	end
+	
+	with "#stop" do
+		it "handles stop without start" do
+			result = clock.stop!
+			expect(result).to be == 0
+			expect(clock.total).to be == 0
+		end
+
+		it "handles multiple stops" do
+			clock.start!
+			first_stop = clock.stop!
+			second_stop = clock.stop!
+			
+			expect(first_stop).to be == second_stop
+			expect(clock.total).to be == first_stop
+		end
+	end
+
 	with "#total" do
 		with "initial duration" do
 			let(:clock) {subject.new(1.5)}
@@ -48,6 +83,21 @@
 			sleep(0.0001)
 			expect(clock.total).to be >= total
 		end
+
+		it "preserves total during start/stop cycles" do
+			# First cycle
+			clock.start!
+			sleep(0.001)
+			first_total = clock.stop!
+			
+			# Second cycle
+			clock.start!
+			sleep(0.001)
+			second_total = clock.stop!
+			
+			expect(second_total).to be > first_total
+			expect(clock.total).to be == second_total
+		end
 	end
 
 	with ".start" do
@@ -76,4 +126,23 @@
 			expect(clock.total).to be > 0.0
 		end
 	end
+	
+	with ".now" do
+		it "produces monotonic timestamps" do
+			first = Async::Clock.now
+			second = Async::Clock.now
+			third = Async::Clock.now
+			
+			expect(second).to be >= first
+			expect(third).to be >= second
+		end
+		
+		it "measures positive durations" do
+			duration = Async::Clock.measure do
+				# Even minimal operations should have non-negative duration
+			end
+			
+			expect(duration).to be >= 0
+		end
+	end
 end

test/async/deadline.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2018-2025, by Samuel Williams.
+
+require "async/deadline"
+
+describe Async::Deadline do
+	with ".start" do
+		it "returns nil for nil timeout" do
+			deadline = subject.start(nil)
+			expect(deadline).to be_nil
+		end
+		
+		it "returns Zero module for zero timeout" do
+			deadline = subject.start(0)
+			expect(deadline).to be == Async::Deadline::Zero
+		end
+		
+		it "returns Zero module for negative timeout" do
+			deadline = subject.start(-1)
+			expect(deadline).to be == Async::Deadline::Zero
+		end
+		
+		it "returns new instance for positive timeout" do
+			deadline = subject.start(5.0)
+			expect(deadline).to be_a(Async::Deadline)
+		end
+	end
+	
+	describe Async::Deadline::Zero do
+		let(:zero) {subject}
+		
+		it "is always expired" do
+			expect(zero.expired?).to be == true
+		end
+		
+		it "has zero remaining time" do
+			expect(zero.remaining).to be == 0
+		end
+	end
+	
+	with "#remaining" do
+		it "initializes with reasonable remaining time" do
+			deadline = subject.new(5.0)
+			expect(deadline.remaining).to be <= 5.0
+		end
+		
+		it "decreases remaining time as time passes" do
+			deadline = subject.new(1.0)
+			
+			# Get initial remaining time
+			first_remaining = deadline.remaining
+			expect(first_remaining).to be <= 1.0
+			
+			# Wait a tiny bit and check again
+			sleep(0.001)
+			
+			second_remaining = deadline.remaining
+			expect(second_remaining).to be < first_remaining
+		end
+		
+		it "can return negative remaining time when expired" do
+			# Create a deadline with very short timeout
+			deadline = subject.new(0.001)  # 1 millisecond
+			
+			# Wait longer than the timeout
+			sleep(0.002)
+			
+			remaining = deadline.remaining
+			expect(remaining).to be < 0  # Should be negative
+		end
+	end
+	
+	with "#expired?" do
+		it "returns false for fresh deadline" do
+			deadline = subject.new(2.0)
+			expect(deadline.expired?).to be == false
+		end
+		
+		it "returns true when deadline has expired" do
+			# Create very short deadline that will expire quickly
+			deadline = subject.new(0.001)
+			
+			# Wait for it to expire
+			sleep(0.01)
+			
+			expect(deadline.expired?).to be == true
+		end
+		
+		it "updates remaining time when checked" do
+			deadline = subject.new(1.0)
+			
+			# Get initial remaining time
+			first_remaining = deadline.remaining
+			
+			# Check if expired (which calls remaining internally)
+			expired = deadline.expired?
+			expect(expired).to be == false
+			
+			# Get remaining time again - should be less
+			second_remaining = deadline.remaining
+			expect(second_remaining).to be < first_remaining
+		end
+	end
+	
+	it "handles sequential operations correctly" do
+		deadline = subject.new(1.0)  # 1 second timeout
+		
+		# First check - should have close to full time
+		first_remaining = deadline.remaining
+		expect(first_remaining).to be <= 1.0
+		expect(first_remaining).to be > 0.5  # Should still have most of the time
+		
+		# Short delay
+		sleep(0.001)
+		
+		# Second check - should be less
+		second_remaining = deadline.remaining
+		expect(second_remaining).to be < first_remaining
+		
+		# Should still not be expired
+		expect(deadline.expired?).to be == false
+	end
+end