Refine interface.

Author: ioquatix

lib/async/scheduler.rb

@@ -553,7 +553,7 @@ def with_timeout(duration, exception = TimeoutError, message = "execution expire
 			if block.arity.zero?
 				yield
 			else
-				yield Timeout.new(@timers, timer, duration)
+				yield Timeout.new(@timers, timer)
 			end
 		ensure
 			timer&.cancel!

lib/async/timeout.rb

@@ -8,31 +8,33 @@ module Async
 	# @public Since *Async v2.24*.
 	class Timeout
 		# Initialize a new timeout.
-		def initialize(timers, handle, duration = nil)
+		def initialize(timers, handle)
 			@timers = timers
 			@handle = handle
-			@duration = duration || (handle.time - timers.now)
 		end
 
-		# @attribute [Numeric] The duration of the timeout.
-		attr :duration
+		# @returns [Numeric] The time remaining until the timeout occurs.
+		def duration
+			@handle.time - @timers.now
+		end
 
 		# Update the duration of the timeout, rescheduling it if necessary.
 		#
-		# The duration is relative to the time the timeout was created.
+		# 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.
 		def duration=(value)
-			delta = value - @duration
-			self.reschedule(time + delta, value)
+			self.reschedule(@timers.now + value)
 		end
 
 		# Adjust the timeout by the specified duration, rescheduling it if necessary.
 		#
+		# 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.
 		# @returns [Numeric] The new time at which the timeout will occur.
 		def adjust(duration)
-			self.reschedule(time + duration, @duration + duration)
+			self.reschedule(time + duration)
 		end
 
 		# @returns [Numeric] The time at which the timeout will occur.
@@ -48,6 +50,11 @@ def time=(value)
 			self.reschedule(value)
 		end
 
+		# @returns [Numeric] The current time in the scheduler.
+		def now
+			@timers.now
+		end
+		
 		# Cancel the timeout.
 		def cancel!
 			@handle.cancel!
@@ -65,13 +72,11 @@ class CancelledError < RuntimeError
 		# Reschedule the timeout to occur at the specified time.
 		#
 		# @parameter time [Numeric] The new time to schedule the timeout for.
-		# @parameter duration [Numeric | Nil] The new duration to assign to the timeout.
 		# @returns [Numeric] The new time at which the timeout will occur.
-		private def reschedule(time, duration = nil)
+		private def reschedule(time)
 			if block = @handle&.block
 				@handle.cancel!
 
-				@duration = duration || (time - @timers.now)
 				@handle = @timers.schedule(time, block)
 
 				return time

releases.md

@@ -5,6 +5,34 @@
   - Ruby v3.1 support is dropped.
   - `Async::Wrapper` which was previously deprecated, is now removed.
 
+### Flexible Timeouts
+
+When {ruby Async::Scheduler#with_timeout} is invoked with a block, it can receive a {ruby Async::Timeout} instance. This allows you to adjust or cancel the timeout while the block is executing. This is useful for long-running tasks that may need to adjust their timeout based on external factors.
+
+``` ruby
+Async do
+	Async::Scheduler.with_timeout(5) do |timeout|
+		# Do some work that may take a while...
+		
+		if some_condition
+			timeout.cancel! # Cancel the timeout
+		else
+			# Add 10 seconds to the current timeout:
+			timeout.adjust(10)
+			
+			# Reduce the timeout by 10 seconds:
+			timeout.adjust(-10)
+			
+			# Set the timeout to 10 seconds from now:
+			timeout.duration = 10
+			
+			# Increase the current duration:
+			timeout.duration += 10
+		end
+	end
+end
+```
+
 ## v2.23.0
 
   - Rename `ASYNC_SCHEDULER_DEFAULT_WORKER_POOL` to `ASYNC_SCHEDULER_WORKER_POOL`.

test/async/timeout.rb

@@ -7,15 +7,15 @@
 	it "can schedule a timeout" do
 		scheduler.with_timeout(1) do |timeout|
 			expect(timeout.time).to be >= 0
-			expect(timeout.duration).to be == 1
+			expect(timeout.duration).to (be > 0).and(be <= 1)
 		end
 	end
 
 	with "#adjust" do
 		it "can adjust the timeout" do
 			scheduler.with_timeout(1) do |timeout|
 				timeout.adjust(1)
-				expect(timeout.duration).to be == 2
+				expect(timeout.duration).to (be > 1).and(be <= 2)
 			end
 		end
 	end
@@ -24,7 +24,14 @@
 		it "can set the timeout duration" do
 			scheduler.with_timeout(1) do |timeout|
 				timeout.duration = 2
-				expect(timeout.duration).to be == 2
+				expect(timeout.duration).to (be > 1).and(be <= 2)
+			end
+		end
+		
+		it "can increase the timeout duration" do
+			scheduler.with_timeout(1) do |timeout|
+				timeout.duration += 2
+				expect(timeout.duration).to (be > 2).and(be <= 3)
 			end
 		end
 	end