async 2.23.1 → 2.24.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 36ac96ecf26e32e4804f8e89909dcb7b5f8cdfbed24a4da1a189d027586bd0b1
-  data.tar.gz: 35fb378abd8183a2a4950a2b57fd4ba6360c740b51a12ff3e67af5a2c443583c
+  metadata.gz: 95c1315007ff80d78bdd1538d2b2963ed951db5aa92906ea6f22560612540cbc
+  data.tar.gz: 03ffadcf7c2523827bd6c49340df0a846f8ab3214593d897b4359b548a765cef
 SHA512:
-  metadata.gz: 5ff90e092ac86b1dd3e5991e48d44d2b6a9abaa1b72d785d3e9419630f3f8fadd241ab21837bbd5ddd4038792e3ac970bf2aa4b2f67f5a473d4be1caa067f1d5
-  data.tar.gz: 5b71b8eae39aee81b3918f1012c76a4306529292626bf6dc95e79ecebcfa53cda304840655eee56c3392b5a912478ff3178ab4624a2f519ad02d6ce70098f1e2
+  metadata.gz: 62c15e0c19e7f3277ca9e4981b0304d5f039367fb0d6b996a8c562be170b3436f66e97f33fcfd5eb0ed8ec84e760ae2b565a022604e026f3b2c797613534fd59
+  data.tar.gz: 79c7148d35f3e06243b3845721b8a1ebcf5fd2e6244eab18ac5a0f42894088334df307c4da52d9d9c59b0d9499e457f0990022d570abf109202416cf168211a1

data/lib/async/scheduler.rb

@@ -7,6 +7,7 @@
 
 require_relative "clock"
 require_relative "task"
+require_relative "timeout"
 require_relative "worker_pool"
 
 require "io/event"
@@ -269,16 +270,6 @@ module Async
 			::Resolv.getaddresses(hostname)
 		end
 		
-		if IO.method_defined?(:timeout)
-			private def get_timeout(io)
-				io.timeout
-			end
-		else
-			private def get_timeout(io)
-				nil
-			end
-		end
-		
 		# Wait for the specified IO to become ready for the specified events.
 		#
 		# @public Since *Async v2*.
@@ -295,7 +286,7 @@ module Async
 				timer = @timers.after(timeout) do
 					fiber.transfer
 				end
-			elsif timeout = get_timeout(io)
+			elsif timeout = io.timeout
 				# Otherwise, if we default to the io's timeout, we raise an exception:
 				timer = @timers.after(timeout) do
 					fiber.raise(::IO::TimeoutError, "Timeout (#{timeout}s) while waiting for IO to become ready!")
@@ -320,7 +311,7 @@ module Async
 			def io_read(io, buffer, length, offset = 0)
 				fiber = Fiber.current
 				
-				if timeout = get_timeout(io)
+				if timeout = io.timeout
 					timer = @timers.after(timeout) do
 						fiber.raise(::IO::TimeoutError, "Timeout (#{timeout}s) while waiting for IO to become readable!")
 					end
@@ -344,7 +335,7 @@ module Async
 				def io_write(io, buffer, length, offset = 0)
 					fiber = Fiber.current
 					
-					if timeout = get_timeout(io)
+					if timeout = io.timeout
 						timer = @timers.after(timeout) do
 							fiber.raise(::IO::TimeoutError, "Timeout (#{timeout}s) while waiting for IO to become writable!")
 						end
@@ -549,7 +540,7 @@ module Async
 		# @parameter duration [Numeric] The time in seconds, in which the task should complete.
 		# @parameter exception [Class] The exception class to raise.
 		# @parameter message [String] The message to pass to the exception.
-		# @yields {|duration| ...} The block to execute with a timeout.
+		# @yields {|timeout| ...} The block to execute with a timeout.
 		def with_timeout(duration, exception = TimeoutError, message = "execution expired", &block)
 			fiber = Fiber.current
 			
@@ -559,7 +550,11 @@ module Async
 				end
 			end
 			
-			yield timer
+			if block.arity.zero?
+				yield
+			else
+				yield Timeout.new(@timers, timer)
+			end
 		ensure
 			timer&.cancel!
 		end
@@ -574,7 +569,7 @@ module Async
 		# @parameter message [String] The message to pass to the exception.
 		# @yields {|duration| ...} The block to execute with a timeout.
 		def timeout_after(duration, exception, message, &block)
-			with_timeout(duration, exception, message) do |timer|
+			with_timeout(duration, exception, message) do
 				yield duration
 			end
 		end

data/lib/async/timeout.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+module Async
+	# Represents a flexible timeout that can be rescheduled or extended.
+	# @public Since *Async v2.24*.
+	class Timeout
+		# Initialize a new timeout.
+		def initialize(timers, handle)
+			@timers = timers
+			@handle = handle
+		end
+		
+		# @returns [Numeric] The time remaining until the timeout occurs, in seconds.
+		def duration
+			@handle.time - @timers.now
+		end
+		
+		# Update the duration of the timeout.
+		#
+		# 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, in seconds.
+		def duration=(value)
+			self.reschedule(@timers.now + value)
+		end
+		
+		# Adjust the timeout by the specified duration.
+		#
+		# 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, in seconds.
+		# @returns [Numeric] The new time at which the timeout will occur.
+		def adjust(duration)
+			self.reschedule(time + duration)
+		end
+		
+		# @returns [Numeric] The time at which the timeout will occur, in seconds since {now}.
+		def time
+			@handle.time
+		end
+		
+		# Assign a new time to the timeout, rescheduling it if necessary.
+		#
+		# @parameter value [Numeric] The new time to assign to the timeout.
+		# @returns [Numeric] The new time at which the timeout will occur.
+		def time=(value)
+			self.reschedule(value)
+		end
+		
+		# @returns [Numeric] The current time in the scheduler, relative to the time of this timeout, in seconds.
+		def now
+			@timers.now
+		end
+		
+		# Cancel the timeout, preventing it from executing.
+		def cancel!
+			@handle.cancel!
+		end
+		
+		# @returns [Boolean] Whether the timeout has been cancelled.
+		def cancelled?
+			@handle.cancelled?
+		end
+		
+		# Raised when attempting to reschedule a cancelled timeout.
+		class CancelledError < RuntimeError
+		end
+		
+		# Reschedule the timeout to occur at the specified time.
+		#
+		# @parameter time [Numeric] The new time to schedule the timeout for.
+		# @returns [Numeric] The new time at which the timeout will occur.
+		private def reschedule(time)
+			if block = @handle&.block
+				@handle.cancel!
+				
+				@handle = @timers.schedule(time, block)
+				
+				return time
+			else
+				raise CancelledError, "Cannot reschedule a cancelled timeout!"
+			end
+		end
+	end
+end

data/lib/async/version.rb

@@ -4,5 +4,5 @@
 # Copyright, 2017-2024, by Samuel Williams.
 
 module Async
-	VERSION = "2.23.1"
+	VERSION = "2.24.0"
 end

data/lib/async/worker_pool.rb

@@ -14,7 +14,7 @@ module Async
 		module BlockingOperationWait
 			# Wait for the given work to be executed.
 			#
-			# @public Since *Async v2.19* and *Ruby v3.4*.
+			# @public Since *Async v2.21* and *Ruby v3.4*.
 			# @asynchronous May be non-blocking.
 			#
 			# @parameter work [Proc] The work to execute on a background thread.

data/readme.md

@@ -35,6 +35,12 @@ Please see the [project documentation](https://socketry.github.io/async/) for mo
 
 Please see the [project releases](https://socketry.github.io/async/releases/index) for all releases.
 
+### v2.24.0
+
+  - Ruby v3.1 support is dropped.
+  - `Async::Wrapper` which was previously deprecated, is now removed.
+  - [Flexible Timeouts](https://socketry.github.io/async/releases/index#flexible-timeouts)
+
 ### v2.23.0
 
   - Rename `ASYNC_SCHEDULER_DEFAULT_WORKER_POOL` to `ASYNC_SCHEDULER_WORKER_POOL`.

data/releases.md

@@ -1,5 +1,38 @@
 # Releases
 
+## v2.24.0
+
+  - 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`.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async
 version: !ruby/object:Gem::Version
-  version: 2.23.1
+  version: 2.24.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -62,7 +62,7 @@ cert_chain:
   Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
   voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
   -----END CERTIFICATE-----
-date: 2025-03-10 00:00:00.000000000 Z
+date: 2025-05-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: console
@@ -157,12 +157,12 @@ files:
 - lib/async/semaphore.rb
 - lib/async/task.md
 - lib/async/task.rb
+- lib/async/timeout.rb
 - lib/async/variable.rb
 - lib/async/version.rb
 - lib/async/waiter.md
 - lib/async/waiter.rb
 - lib/async/worker_pool.rb
-- lib/async/wrapper.rb
 - lib/kernel/async.rb
 - lib/kernel/sync.rb
 - lib/metrics/provider/async.rb

data/lib/async/wrapper.rb

@@ -1,67 +0,0 @@
-# frozen_string_literal: true
-
-# Released under the MIT License.
-# Copyright, 2017-2024, by Samuel Williams.
-# Copyright, 2017, by Kent Gruber.
-
-warn "Async::Wrapper is deprecated and will be removed on 2025-03-31. Please use native interfaces instead.", uplevel: 1, category: :deprecated
-
-module Async
-	# Represents an asynchronous IO within a reactor.
-	# @deprecated With no replacement. Prefer native interfaces.
-	class Wrapper
-		# An exception that occurs when the asynchronous operation was cancelled.
-		class Cancelled < StandardError
-		end
-		
-		# @parameter io the native object to wrap.
-		# @parameter reactor [Reactor] the reactor that is managing this wrapper, or not specified, it's looked up by way of {Task.current}.
-		def initialize(io, reactor = nil)
-			@io = io
-			@reactor = reactor
-			
-			@timeout = nil
-		end
-		
-		attr_accessor :reactor
-		
-		# Dup the underlying IO.
-		def dup
-			self.class.new(@io.dup)
-		end
-		
-		# The underlying native `io`.
-		attr :io
-		
-		# Wait for the io to become readable.
-		def wait_readable(timeout = @timeout)
-			@io.to_io.wait_readable(timeout) or raise TimeoutError
-		end
-		
-		# Wait for the io to become writable.
-		def wait_priority(timeout = @timeout)
-			@io.to_io.wait_priority(timeout) or raise TimeoutError
-		end
-		
-		# Wait for the io to become writable.
-		def wait_writable(timeout = @timeout)
-			@io.to_io.wait_writable(timeout) or raise TimeoutError
-		end
-		
-		# Wait fo the io to become either readable or writable.
-		# @parameter duration [Float] timeout after the given duration if not `nil`.
-		def wait_any(timeout = @timeout)
-			@io.to_io.wait(::IO::READABLE|::IO::WRITABLE|::IO::PRIORITY, timeout) or raise TimeoutError
-		end
-		
-		# Close the underlying IO.
-		def close
-			@io.close
-		end
-		
-		# Whether the underlying IO is closed.
-		def closed?
-			@io.closed?
-		end
-	end
-end