async 2.36.0 → 2.37.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b514097c721290749f38fed73721c5cb6d17af2a8af189f5a8e537f7b30c14d3
-  data.tar.gz: 3eba30b0a03bdb9f9da1d1e4eeb6b11ec3224c0f3d02f27cc07ac1e5e7d7a41e
+  metadata.gz: 59107a94e01d137ccdba59b8204cfbb0a223418e3ce5374386fe9c12bf7f455d
+  data.tar.gz: 7a2dfe8b7b15bbe059e898faa3fd59b1b024e4156744897246368763ed35a106
 SHA512:
-  metadata.gz: 9ea8d371279ec9bf8feeaa85895f25733247c8ecb059d599f34e8ecc85b4b124c05dee5421414d28c24316d7c4e69bdff622c31b182e9f883456836a6aab17ed
-  data.tar.gz: 55ddefa4f011c2dccf235043cad5ad334418c394ced59a960b993d18ead0850f7d60875a3edbdc55418d3a9d3045cef1d607170fea0ae484f4dc62bc13f15ca2
+  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"
 

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,26 @@
 # 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

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.36.0"
+	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,10 @@ 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.
@@ -73,10 +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.
-
 ## See Also
 
   - [async-http](https://github.com/socketry/async-http) — Asynchronous HTTP client/server.

data/releases.md

@@ -1,5 +1,9 @@
 # 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.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async
 version: !ruby/object:Gem::Version
-  version: 2.36.0
+  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