Add Async::Deadline for managing compound timeouts.

Author: samuel-williams-shopify

lib/async/deadline.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require_relative "clock"
+
+module Async
+	# Manages a countdown timer for timeout operations.
+	# Provides precise deadline tracking for compound operations to prevent timeout accumulation where multiple operations could exceed user timeouts.
+	# @public Since *Async v2.31*.
+	class Deadline
+		# Singleton module for immediate timeouts (zero or negative).
+		# Avoids object allocation for performance.
+		module Zero
+			def self.expired?
+				true
+			end
+			
+			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

@@ -76,4 +76,81 @@
 			expect(clock.total).to be > 0.0
 		end
 	end
+	
+	with "monotonicity" 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
+	
+	with "edge cases" do
+		it "handles multiple start/stop cycles" do
+			3.times do
+				clock.start!
+				# Calling start! again should not change the start time
+				original_start = clock.instance_variable_get(:@started)
+				clock.start!
+				expect(clock.instance_variable_get(:@started)).to be == original_start
+				clock.stop!
+			end
+			
+			expect(clock.total).to be >= 0
+		end
+		
+		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
+		
+		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
+		
+		it "includes running time in total" do
+			base_total = clock.total
+			expect(base_total).to be == 0
+			
+			clock.start!
+			sleep(0.001)
+			running_total = clock.total
+			
+			expect(running_total).to be > base_total
+			expect(clock.instance_variable_get(:@started)).not.to be_nil
+		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