async 2.35.3 → 2.37.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7c439d8ba1591623b695ccd1dd4fe68f822fedd589291a7bdd79a53ce9c430d7
-  data.tar.gz: cc8902bc5b15f446df404967e1832c9847eb0bcad879565508f6688bd0a5c92a
+  metadata.gz: 59107a94e01d137ccdba59b8204cfbb0a223418e3ce5374386fe9c12bf7f455d
+  data.tar.gz: 7a2dfe8b7b15bbe059e898faa3fd59b1b024e4156744897246368763ed35a106
 SHA512:
-  metadata.gz: c2bfeb61c9f9ddad7576c66be0b637bee5934159e9388fe21cd0b1e8e5df804b5818194ef812d6249570411591d232a4c570fc6c6bcd02d67496e7aaf8950467
-  data.tar.gz: 2454b411f93e6e86e25030bdd358eba7ed38536928ab64dc64b1dc10e3dff152ac4005ad27bdf3d4e801c49d69c2b386f7ca08961d90015dbe86fa2e9bccc5cf
+  metadata.gz: 03c75631a638f69c5e3bbd720c75c9edc1bb7f9a71a296fdc5f089532d0eb86d91babc5760cd97afdbe60ae1aabd226de2ae325b5d8f458538376faa18f3d820
+  data.tar.gz: c328e8223cd12b1e44329737156163fc152f981caedd7af7bb5b1f3920ed96cf6a93f18564a49d9d2e52f03bdd2e61aec39b519e5c13c9830553e2c709c0d486

data/lib/async/clock.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2018-2025, by Samuel Williams.
+# Copyright, 2018-2026, by Samuel Williams.
+# Copyright, 2026, by Shopify Inc.
 
 module Async
 	# A convenient wrapper around the internal monotonic clock.

data/lib/async/error.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+module Async
+	# Raised if a timeout occurs on a specific Fiber. Handled gracefully by `Task`.
+	# @public Since *Async v1*.
+	class TimeoutError < StandardError
+		# Create a new timeout error.
+		#
+		# @parameter message [String] The error message.
+		def initialize(message = "execution expired")
+			super
+		end
+	end
+end

data/lib/async/fork_handler.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2025, by Shopify Inc.
-# Copyright, 2025, by Samuel Williams.
+# Copyright, 2025-2026, by Shopify Inc.
+# Copyright, 2025-2026, by Samuel Williams.
 
 module Async
 	# Private module that hooks into Process._fork to handle fork events.

data/lib/async/loop.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "console"
+
+module Async
+	# @namespace
+	module Loop
+		# Execute a block repeatedly at quantized (time-aligned) intervals.
+		#
+		# The alignment is computed modulo the current clock time in seconds. For example, with
+		# `interval: 60`, executions will occur at 00:00, 01:00, 02:00, etc., regardless of when
+		# the loop is started. With `interval: 300` (5 minutes), executions align to 00:00, 00:05,
+		# 00:10, etc.
+		#
+		# This is particularly useful for tasks that should run at predictable wall-clock times,
+		# such as metrics collection, periodic cleanup, or scheduled jobs that need to align
+		# across multiple processes.
+		#
+		# If an error occurs during block execution, it is logged and the loop continues.
+		#
+		# @example Run every minute at :00 seconds:
+		# 	Async::Loop.quantized(interval: 60) do
+		# 		puts "Current time: #{Time.now}"
+		# 	end
+		#
+		# @example Run every 5 minutes aligned to the hour:
+		# 	Async::Loop.quantized(interval: 300) do
+		# 		collect_metrics
+		# 	end
+		#
+		# @parameter interval [Numeric] The interval in seconds. Executions will align to multiples of this interval based on the current time.
+		# @yields The block to execute at each interval.
+		#
+		# @public Since *Async v2.37*.
+		def self.quantized(interval: 60, &block)
+			while true
+				# Compute the wait time to the next interval:
+				wait = interval - (Time.now.to_f % interval)
+				if wait.positive?
+					# Sleep until the next interval boundary:
+					sleep(wait)
+				end
+				
+				begin
+					yield
+				rescue => error
+					Console.error(self, "Loop error:", error)
+				end
+			end
+		end
+		
+		# Execute a block repeatedly with a fixed delay between executions.
+		#
+		# Unlike {quantized}, this method waits for the specified interval *after* each execution
+		# completes. This means the actual time between the start of successive executions will be
+		# `interval + execution_time`.
+		#
+		# If an error occurs during block execution, it is logged and the loop continues.
+		#
+		# @example Run every 5 seconds (plus execution time):
+		# 	Async::Loop.periodic(interval: 5) do
+		# 		process_queue
+		# 	end
+		#
+		# @parameter interval [Numeric] The delay in seconds between executions.
+		# @yields The block to execute periodically.
+		#
+		# @public Since *Async v2.37*.
+		def self.periodic(interval: 60, &block)
+			while true
+				begin
+					yield
+				rescue => error
+					Console.error(self, "Loop error:", error)
+				end
+				
+				sleep(interval)
+			end
+		end
+	end
+end

data/lib/async/node.rb

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2017-2025, by Samuel Williams.
+# Copyright, 2017-2026, by Samuel Williams.
 # Copyright, 2017, by Kent Gruber.
 # Copyright, 2022, by Shannon Skipper.
-# Copyright, 2025, by Shopify Inc.
+# Copyright, 2025-2026, by Shopify Inc.
 
 require "fiber/annotation"
 
@@ -295,6 +295,12 @@ module Async
 			end
 		end
 		
+		# Wait for this node to complete. By default, nodes cannot be waited on.
+		# Subclasses like Task override this method to provide waiting functionality.
+		def wait
+			nil
+		end
+		
 		# Whether the node has been stopped.
 		def stopped?
 			@children.nil?

data/lib/async/promise.rb

@@ -4,6 +4,9 @@
 # Copyright, 2025, by Shopify Inc.
 # Copyright, 2025-2026, by Samuel Williams.
 
+require_relative "error"
+require_relative "deadline"
+
 module Async
 	# A promise represents a value that will be available in the future.
 	# Unlike Condition, once resolved (or rejected), all future waits return immediately 
@@ -77,17 +80,23 @@ module Async
 		# Wait for the promise to be resolved and return the value.
 		# If already resolved, returns immediately. If rejected, raises the stored exception.
 		#
+		# @parameter timeout [Numeric | Nil] Maximum time to wait. If nil, waits indefinitely. If 0, raises immediately if not resolved.
 		# @returns [Object] The resolved value.
 		# @raises [Exception] The rejected or cancelled exception.
-		def wait
+		# @raises [Async::TimeoutError] If timeout expires before the promise is resolved.
+		def wait(timeout: nil)
 			@mutex.synchronize do
 				# Increment waiting count:
 				@waiting += 1
 				
 				begin
 					# Wait for resolution if not already resolved:
-					until @resolved
-						@condition.wait(@mutex)
+					unless @resolved
+						if timeout.nil?
+							wait_indefinitely
+						else
+							wait_with_timeout(timeout)
+						end
 					end
 					
 					# Return value or raise exception based on resolution type:
@@ -104,6 +113,39 @@ module Async
 			end
 		end
 		
+		# Wait indefinitely for the promise to be resolved.
+		private def wait_indefinitely
+			until @resolved
+				@condition.wait(@mutex)
+			end
+		end
+		
+		# Wait for the promise to be resolved, respecting the deadline timeout.
+		# @parameter timeout [Numeric] The timeout duration.
+		# @raises [Async::TimeoutError] If the timeout expires before resolution.
+		private def wait_with_timeout(timeout)
+			# Create deadline for timeout tracking:
+			deadline = Deadline.start(timeout)
+			
+			# Handle immediate timeout (non-blocking):
+			if deadline == Deadline::Zero && !@resolved
+				raise Async::TimeoutError, "Promise wait not resolved!"
+			end
+			
+			# Wait with deadline tracking:
+			until @resolved
+				# Get remaining time for this wait iteration:
+				remaining = deadline.remaining
+				
+				# Check if deadline has expired before waiting:
+				if remaining <= 0
+					raise Async::TimeoutError, "Promise wait timed out!"
+				end
+				
+				@condition.wait(@mutex, remaining)
+			end
+		end
+		
 		# Resolve the promise with a value.
 		# All current and future waiters will receive this value.
 		# Can only be called once - subsequent calls are ignored.

data/lib/async/scheduler.rb

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2025, by Samuel Williams.
+# Copyright, 2020-2026, by Samuel Williams.
 # Copyright, 2020, by Jun Jiang.
 # Copyright, 2021, by Julien Portalier.
-# Copyright, 2025, by Shopify Inc.
+# Copyright, 2025-2026, by Shopify Inc.
 
 require_relative "clock"
 require_relative "task"

data/lib/async/task.rb

@@ -1,36 +1,52 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2017-2025, by Samuel Williams.
+# Copyright, 2017-2026, by Samuel Williams.
 # Copyright, 2017, by Kent Gruber.
 # Copyright, 2017, by Devin Christensen.
 # Copyright, 2020, by Patrik Wenger.
 # Copyright, 2023, by Math Ieu.
 # Copyright, 2025, by Shigeru Nakajima.
-# Copyright, 2025, by Shopify Inc.
+# Copyright, 2025-2026, by Shopify Inc.
 
 require "fiber"
 require "console"
 
 require_relative "node"
 require_relative "condition"
+require_relative "error"
 require_relative "promise"
 require_relative "stop"
 
 Fiber.attr_accessor :async_task
 
 module Async
-	# Raised if a timeout occurs on a specific Fiber. Handled gracefully by `Task`.
-	# @public Since *Async v1*.
-	class TimeoutError < StandardError
-		# Create a new timeout error.
-		#
-		# @parameter message [String] The error message.
-		def initialize(message = "execution expired")
-			super
-		end
-	end
-	
+	# Represents a sequential unit of work, defined by a block, which is executed concurrently with other tasks. A task can be in one of the following states: `initialized`, `running`, `completed`, `failed`, `cancelled` or `stopped`.
+	#
+	# ```mermaid
+	# stateDiagram-v2
+	# [*] --> Initialized
+	# Initialized --> Running : Run
+	#
+	# Running --> Completed : Return Value
+	# Running --> Failed : Exception
+	#
+	# Completed --> [*]
+	# Failed --> [*]
+	#
+	# Running --> Stopped : Stop
+	# Stopped --> [*]
+	# Completed --> Stopped : Stop
+	# Failed --> Stopped : Stop
+	# Initialized --> Stopped : Stop
+	# ```
+	#
+	# @example Creating a task that sleeps for 1 second.
+	# 	require "async"
+	# 	Async do |task|
+	# 		sleep(1)
+	# 	end
+	#
 	# @public Since *Async v1*.
 	class Task < Node
 		# Raised when a child task is created within a task that has finished execution.
@@ -258,11 +274,43 @@ module Async
 			begin
 				@promise.wait
 			rescue Promise::Cancel
-				# For backward compatibility, stopped tasks return nil
+				# For backward compatibility, stopped tasks return nil:
 				return nil
 			end
 		end
 		
+		# For compatibility with `Thread#join` and similar interfaces.
+		alias join wait
+		
+		# Wait on all non-transient children to complete, recursively, then wait on the task itself, if it is not the current task.
+		#
+		# If any child task fails with an exception, that exception will be raised immediately, and remaining children may not be waited on.
+		#
+		# @example Waiting on all children.
+		# 	Async do |task|
+		# 		child = task.async do
+		# 			sleep(0.01)
+		# 		end
+		# 		task.wait_all # Will wait on the child task.
+		# 	end
+		#
+		# @raises [StandardError] If any child task failed with an exception, that exception will be raised.
+		# @returns [Object | Nil] The final expression/result of the task's block, or nil if called from within the task.
+		# @asynchronous This method is thread-safe.
+		def wait_all
+			@children&.each do |child|
+				# Skip transient tasks
+				next if child.transient?
+				
+				child.wait_all
+			end
+			
+			# Only wait on the task if we're not waiting on ourselves:
+			unless self.current?
+				return self.wait
+			end
+		end
+		
 		# Access the result of the task without waiting. May be nil if the task is not completed. Does not raise exceptions.
 		def result
 			value = @promise.value

data/lib/async/version.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2017-2025, by Samuel Williams.
+# Copyright, 2017-2026, by Samuel Williams.
 
 module Async
-	VERSION = "2.35.3"
+	VERSION = "2.37.0"
 end

data/lib/async.rb

@@ -6,6 +6,7 @@
 
 require_relative "async/version"
 require_relative "async/reactor"
+require_relative "async/loop"
 
 require_relative "kernel/async"
 require_relative "kernel/sync"

data/license.md

@@ -31,7 +31,7 @@ Copyright, 2025, by Jahfer Husain.
 Copyright, 2025, by Mark Montroy.  
 Copyright, 2025, by Shigeru Nakajima.  
 Copyright, 2025, by Alan Wu.  
-Copyright, 2025, by Shopify Inc.  
+Copyright, 2025-2026, by Shopify Inc.  
 Copyright, 2025, by Josh Teeter.  
 Copyright, 2025, by Jatin Goyal.  
 Copyright, 2025, by Yuhi Sato.  

data/readme.md

@@ -35,6 +35,15 @@ 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.37.0
+
+  - Introduce `Async::Loop` for robust, time-aligned loops.
+
+### v2.36.0
+
+  - Introduce `Task#wait_all` which recursively waits for all children and self, excepting the current task.
+  - Introduce `Task#join` as an alias for `Task#wait` for compatibility with `Thread#join` and similar interfaces.
+
 ### v2.35.3
 
   - `Async::Clock` now implements `#as_json` and `#to_json` for nicer log formatting.
@@ -68,17 +77,6 @@ Please see the [project releases](https://socketry.github.io/async/releases/inde
 
   - 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.
-  - 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.
-
 ## See Also
 
   - [async-http](https://github.com/socketry/async-http) — Asynchronous HTTP client/server.

data/releases.md

@@ -1,5 +1,14 @@
 # Releases
 
+## v2.37.0
+
+  - Introduce `Async::Loop` for robust, time-aligned loops.
+
+## v2.36.0
+
+  - Introduce `Task#wait_all` which recursively waits for all children and self, excepting the current task.
+  - Introduce `Task#join` as an alias for `Task#wait` for compatibility with `Thread#join` and similar interfaces.
+
 ## v2.35.3
 
   - `Async::Clock` now implements `#as_json` and `#to_json` for nicer log formatting.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async
 version: !ruby/object:Gem::Version
-  version: 2.35.3
+  version: 2.37.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -161,10 +161,12 @@ files:
 - lib/async/condition.rb
 - lib/async/console.rb
 - lib/async/deadline.rb
+- lib/async/error.rb
 - lib/async/fork_handler.rb
 - lib/async/idler.rb
 - lib/async/limited_queue.rb
 - lib/async/list.rb
+- lib/async/loop.rb
 - lib/async/node.rb
 - lib/async/notification.rb
 - lib/async/priority_queue.rb
@@ -175,7 +177,6 @@ files:
 - lib/async/semaphore.md
 - lib/async/semaphore.rb
 - lib/async/stop.rb
-- lib/async/task.md
 - lib/async/task.rb
 - lib/async/timeout.rb
 - lib/async/variable.rb

data/lib/async/task.md

@@ -1,30 +0,0 @@
-A sequence of instructions, defined by a block, which is executed sequentially and managed by the scheduler. A task can be in one of the following states: `initialized`, `running`, `completed`, `failed`, `cancelled` or `stopped`.
-
-```mermaid
-stateDiagram-v2
-[*] --> Initialized
-Initialized --> Running : Run
-
-Running --> Completed : Return Value
-Running --> Failed : Exception
-
-Completed --> [*]
-Failed --> [*]
-
-Running --> Stopped : Stop
-Stopped --> [*]
-Completed --> Stopped : Stop
-Failed --> Stopped : Stop
-Initialized --> Stopped : Stop
-```
-
-## Example
-
-```ruby
-require "async"
-
-# Create an asynchronous task that sleeps for 1 second:
-Async do |task|
-	sleep(1)
-end
-```