async 2.30.0 → 2.32.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1423e2d1cc2a1e1aec71d5e70640a0b8c8069d6a2b2af9da63f7bed3d0c9d548
-  data.tar.gz: 2529e362cd8141d9fa0d8a6ea29fd0d74298630cdd8d4034633c20365a2c5491
+  metadata.gz: 5a816b65e2cdf3f1f9ee99d421b32f13ed00c858bfa2b1ff0f814cf33c9dd470
+  data.tar.gz: 85dc9dfad110e4ae2f0d4db45db9b1f941b797891f945da1caaa302df233f813
 SHA512:
-  metadata.gz: 3455b22a4ea6a6e438e1da05ab9c4f5e7cf4d7f8f465138814c71743b2a6d7c1b1525cc3bb13b065b0aa67d0a57d5409d23cc101c61bd026c6ace345919f0005
-  data.tar.gz: fb21c61222c5067d272f8e5b845fcdef9ce2f99ab831cebf6575e94068b5e22f365569a2b2af1c5ec704b7e1bf53de93ef4c6143c014e5d77f9995908761b975
+  metadata.gz: e6cf114ad81e9eb511504ed44b719f9838ad84623fea14aab43acd531a9d8493b92eb0a24a49bb410670c0be82c8de5617280f39e984f1d9477c4828d96d2fc5
+  data.tar.gz: 2acb3e1516b2670a57cb717713d882f9d75807864924bf7aa691aa82cd5406a2b273c7aa813a30037a3dabce338095eb7faa5efff8f5f5b56290a07b3b0927b5

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

@@ -102,12 +102,15 @@ module Async
 		end
 		
 		# @returns [Integer] The number of fibers waiting to dequeue.
-		def waiting
+		def waiting_count
 			@mutex.synchronize do
 				@waiting.size
 			end
 		end
 		
+		# @deprecated Use {#waiting_count} instead.
+		alias waiting waiting_count
+		
 		# Add an item to the queue.
 		#
 		# @parameter item [Object] The item to add to the queue.

data/lib/async/queue.rb

@@ -53,6 +53,11 @@ module Async
 			@delegate.empty?
 		end
 		
+		# @returns [Integer] The number of tasks waiting for an item.
+		def waiting_count
+			@delegate.num_waiting
+		end
+		
 		# Add an item to the queue.
 		def push(item)
 			@delegate.push(item)

data/lib/async/version.rb

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

data/readme.md

@@ -35,6 +35,14 @@ 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.32.0
+
+  - Introduce `Queue#waiting_count` and `PriorityQueue#waiting_count`. Generally for statistics/testing purposes only.
+
+### 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.
@@ -76,22 +84,6 @@ This release introduces thread-safety as a core concept of Async. Many core clas
 
   - Updated documentation and agent context.
 
-### v2.27.0
-
-  - `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)
-
 ## See Also
 
   - [async-http](https://github.com/socketry/async-http) — Asynchronous HTTP client/server.

data/releases.md

@@ -1,5 +1,13 @@
 # Releases
 
+## v2.32.0
+
+  - Introduce `Queue#waiting_count` and `PriorityQueue#waiting_count`. Generally for statistics/testing purposes only.
+
+## 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.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async
 version: !ruby/object:Gem::Version
-  version: 2.30.0
+  version: 2.32.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -159,6 +159,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