async 2.29.1 → 2.31.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f3ecf839913862d1e1638fd14c067e57b4e68a469bc8805d6dd4d568829ab02c
-  data.tar.gz: 10a3624e0c564f7d895f77738e88b8a2e0b89ca58fd285488b32bf57509ff3de
+  metadata.gz: 2021787bfa001830a1a65e77ca0162349f4b7c21206077a8583f7cb81268a6b4
+  data.tar.gz: af5adae74c2b6e31df15e8885f7f5cad8f18090390d386c8d6373cebca5d1be7
 SHA512:
-  metadata.gz: 4b3ad1290e807941399e29efe94faf04bbc721a4d59b06292abaac482acc27fac25834629a2869a343439594cd8f0576c01af3ccf9bc9f5661885f8fdbf3bcf1
-  data.tar.gz: 89c92f9cf32ab403100ea4c00e3d93a2257aac2dd036473ecde04efb5182cffb2d91e76185b7d48f24f9ccceaf3e8dec6609549e96b72225012a964d5d93c207
+  metadata.gz: 27db90ffb96b0b179a311023e73f02837e668a81c7979406b1becf1278f2af8af0aebf24947748feac6b5ba9da0774073d0ae5925e747b7a3c0eb78803ef83c2
+  data.tar.gz: 14328112f76c82aa10aff761e23897dec82ae7512a6c5fd72a4f3708c9a828f2d53538a22e49abecfd9bdf30e243c63bb7f4c2feccd088daf208143a77d756c2

data/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

data/lib/async/priority_queue.rb

@@ -39,8 +39,8 @@ module Async
 				condition.signal
 			end
 			
-			def wait_for_value(mutex)
-				condition.wait(mutex)
+			def wait_for_value(mutex, timeout = nil)
+				condition.wait(mutex, timeout)
 				return self.value
 			end
 			
@@ -55,6 +55,8 @@ module Async
 			end
 		end
 		
+		private_constant :Waiter
+		
 		# Create a new priority queue.
 		#
 		# @parameter parent [Interface(:async) | Nil] The parent task to use for async operations.
@@ -81,6 +83,11 @@ module Async
 			end
 		end
 		
+		# @returns [Boolean] Whether the queue is closed.
+		def closed?
+			@closed
+		end
+		
 		# @attribute [Array] The items in the queue.
 		attr :items
 		
@@ -153,13 +160,14 @@ module Async
 		
 		# Remove and return the next item from the queue.
 		#
-		# If the queue is empty, this method will block until an item is available.
+		# If the queue is empty, this method will block until an item is available or timeout expires.
 		# Fibers are served in priority order, with higher priority fibers receiving
 		# items first.
 		#
 		# @parameter priority [Numeric] The priority of this consumer (higher = served first).
-		# @returns [Object] The next item in the queue.
-		def dequeue(priority: 0)
+		# @parameter timeout [Numeric, nil] Maximum time to wait for an item. If nil, waits indefinitely. If 0, returns immediately.
+		# @returns [Object, nil] The next item in the queue, or nil if timeout expires.
+		def dequeue(priority: 0, timeout: nil)
 			@mutex.synchronize do
 				# If queue is closed and empty, return nil immediately:
 				if @closed && @items.empty?
@@ -174,6 +182,9 @@ module Async
 					end
 				end
 				
+				# Handle immediate timeout (non-blocking)
+				return nil if timeout == 0
+				
 				# Need to wait - create our own condition variable and add to waiting queue:
 				sequence = @sequence
 				@sequence += 1
@@ -185,7 +196,7 @@ module Async
 					@waiting.push(waiter)
 					
 					# Wait for our specific condition variable to be signaled:
-					return waiter.wait_for_value(@mutex)
+					return waiter.wait_for_value(@mutex, timeout)
 				ensure
 					waiter&.invalidate!
 				end
@@ -195,8 +206,10 @@ module Async
 		# Compatibility with {::Queue#pop}.
 		#
 		# @parameter priority [Numeric] The priority of this consumer.
-		def pop(priority: 0)
-			self.dequeue(priority: priority)
+		# @parameter timeout [Numeric, nil] Maximum time to wait for an item. If nil, waits indefinitely. If 0, returns immediately.
+		# @returns [Object, nil] The dequeued item, or nil if timeout expires.
+		def pop(priority: 0, timeout: nil)
+			self.dequeue(priority: priority, timeout: timeout)
 		end
 		
 		# Process each item in the queue.

data/lib/async/queue.rb

@@ -73,13 +73,17 @@ module Async
 		end
 		
 		# Remove and return the next item from the queue.
-		def dequeue
-			@delegate.pop
+		# @parameter timeout [Numeric, nil] Maximum time to wait for an item. If nil, waits indefinitely. If 0, returns immediately.
+		# @returns [Object, nil] The dequeued item, or nil if timeout expires.
+		def dequeue(timeout: nil)
+			@delegate.pop(timeout: timeout)
 		end
 		
 		# Compatibility with {::Queue#pop}.
-		def pop(...)
-			@delegate.pop(...)
+		# @parameter timeout [Numeric, nil] Maximum time to wait for an item. If nil, waits indefinitely. If 0, returns immediately.
+		# @returns [Object, nil] The dequeued item, or nil if timeout expires.
+		def pop(timeout: nil)
+			@delegate.pop(timeout: timeout)
 		end
 		
 		# Process each item in the queue.

data/lib/async/version.rb

@@ -4,5 +4,5 @@
 # Copyright, 2017-2025, by Samuel Williams.
 
 module Async
-	VERSION = "2.29.1"
+	VERSION = "2.31.0"
 end

data/readme.md

@@ -35,6 +35,17 @@ 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.31.0
+
+  - 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.
+  - Add timeout support to `Async::PriorityQueue#dequeue` and `Async::PriorityQueue#pop` methods.
+  - Add `closed?` method to `Async::PriorityQueue` for full queue interface compatibility.
+  - Support non-blocking operations using `timeout: 0` parameter.
+
 ### v2.29.0
 
 This release introduces thread-safety as a core concept of Async. Many core classes now have thread-safe guarantees, allowing them to be used safely across multiple threads.
@@ -74,23 +85,6 @@ This release introduces thread-safety as a core concept of Async. Many core clas
   - `Async::Task#stop` supports an optional `cause:` argument (that defaults to `$!`), which allows you to specify the cause (exception) for stopping the task.
   - Add thread-safety agent context.
 
-### v2.26.0
-
-  - `Async::Notification#signal` now returns `true` if a task was signaled, `false` otherwise, providing better feedback for notification operations.
-  - `require "async/limited_queue"` is required to use `Async::LimitedQueue` without a deprecation warning. `Async::LimitedQueue` is not deprecated, but it's usage via `async/queue` is deprecated.
-  - `Async::Task#sleep` is deprecated with no replacement.
-  - `Async::Task.yield` is deprecated with no replacement.
-  - `Async::Scheduler#async` is deprecated, use `Async{}`, `Sync{}` or `Async::Task#async` instead.
-  - Agent context is now available, via the [`agent-context` gem](https://github.com/ioquatix/agent-context).
-  - [`Async::Barrier` Improvements](https://socketry.github.io/async/releases/index#async::barrier-improvements)
-  - [Introduce `Async::Queue#close`](https://socketry.github.io/async/releases/index#introduce-async::queue#close)
-
-### v2.25.0
-
-  - Added support for `io_select` hook in the fiber scheduler, allowing non-blocking `IO.select` operations. This enables better integration with code that uses `IO.select` for multiplexing IO operations.
-  - [Use `IO::Event::WorkerPool` for Blocking Operations](https://socketry.github.io/async/releases/index#use-io::event::workerpool-for-blocking-operations)
-  - [Better handling of `IO#close` using `fiber_interrupt`](https://socketry.github.io/async/releases/index#better-handling-of-io#close-using-fiber_interrupt)
-
 ## See Also
 
   - [async-http](https://github.com/socketry/async-http) — Asynchronous HTTP client/server.

data/releases.md

@@ -1,5 +1,16 @@
 # Releases
 
+## v2.31.0
+
+  - 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.
+  - Add timeout support to `Async::PriorityQueue#dequeue` and `Async::PriorityQueue#pop` methods.
+  - Add `closed?` method to `Async::PriorityQueue` for full queue interface compatibility.
+  - Support non-blocking operations using `timeout: 0` parameter.
+
 ## v2.29.0
 
 This release introduces thread-safety as a core concept of Async. Many core classes now have thread-safe guarantees, allowing them to be used safely across multiple threads.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async
 version: !ruby/object:Gem::Version
-  version: 2.29.1
+  version: 2.31.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -38,6 +38,7 @@ authors:
 - Sokolov Yura
 - Stefan Wrobel
 - Trevor Turk
+autorequire:
 bindir: bin
 cert_chain:
 - |
@@ -69,7 +70,7 @@ cert_chain:
   Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
   voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
   -----END CERTIFICATE-----
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2025-09-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: console
@@ -141,6 +142,8 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.18'
+description:
+email:
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -159,6 +162,7 @@ files:
 - lib/async/condition.md
 - lib/async/condition.rb
 - lib/async/console.rb
+- lib/async/deadline.rb
 - lib/async/idler.rb
 - lib/async/limited_queue.rb
 - lib/async/list.rb
@@ -195,6 +199,7 @@ metadata:
   documentation_uri: https://socketry.github.io/async/
   funding_uri: https://github.com/sponsors/ioquatix/
   source_code_uri: https://github.com/socketry/async.git
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -209,7 +214,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.0.dev
+rubygems_version: 3.5.22
+signing_key:
 specification_version: 4
 summary: A concurrency framework for Ruby.
 test_files: []