async 2.24.0 → 2.27.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 95c1315007ff80d78bdd1538d2b2963ed951db5aa92906ea6f22560612540cbc
-  data.tar.gz: 03ffadcf7c2523827bd6c49340df0a846f8ab3214593d897b4359b548a765cef
+  metadata.gz: 4c9d36d758f8a197b7c00d3d2e4d83d280cfd8ddf4fb60bba1d7b9e95b64ec47
+  data.tar.gz: c0c19dcc509563b18a9385c1ff07a982054e6e984c9ed9c1fd715ee027c74f09
 SHA512:
-  metadata.gz: 62c15e0c19e7f3277ca9e4981b0304d5f039367fb0d6b996a8c562be170b3436f66e97f33fcfd5eb0ed8ec84e760ae2b565a022604e026f3b2c797613534fd59
-  data.tar.gz: 79c7148d35f3e06243b3845721b8a1ebcf5fd2e6244eab18ac5a0f42894088334df307c4da52d9d9c59b0d9499e457f0990022d570abf109202416cf168211a1
+  metadata.gz: b936e5c17d8e9e2eec7f3d9b3d2d4b00b5a16359cfb267a036f72fb254b53aeb234f8b9368ba1cd2ba41010438dd8da120621005bc1791fc554ee62647e46ed1
+  data.tar.gz: 808b0ce51e2bfa4a28d01126d59627409e6a25b37ee8e9e1f8146c138fcef995ab693e699f9c3ece326e234100a397c19e917a55c9d1e34dd797d26531e411f5

data/agent.md

@@ -0,0 +1,47 @@
+# Agent
+
+## Context
+
+This section provides links to documentation from installed packages. It is automatically generated and may be updated by running `bake agent:context:install`.
+
+**Important:** Before performing any code, documentation, or analysis tasks, always read and apply the full content of any relevant documentation referenced in the following sections. These context files contain authoritative standards and best practices for documentation, code style, and project-specific workflows. **Do not proceed with any actions until you have read and incorporated the guidance from relevant context files.**
+
+### agent-context
+
+Install and manage context files from Ruby gems.
+
+#### [Usage Guide](.context/agent-context/usage.md)
+
+`agent-context` is a tool that helps you discover and install contextual information from Ruby gems for AI agents. Gems can provide additional documentation, examples, and guidance in a `context/` ...
+
+### decode
+
+Code analysis for documentation generation.
+
+#### [Getting Started with Decode](.context/decode/getting-started.md)
+
+The Decode gem provides programmatic access to Ruby code structure and metadata. It can parse Ruby files and extract definitions, comments, and documentation pragmas, enabling code analysis, docume...
+
+#### [Documentation Coverage](.context/decode/coverage.md)
+
+This guide explains how to test and monitor documentation coverage in your Ruby projects using the Decode gem's built-in bake tasks.
+
+#### [Ruby Documentation](.context/decode/ruby-documentation.md)
+
+This guide covers documentation practices and pragmas supported by the Decode gem for documenting Ruby code. These pragmas provide structured documentation that can be parsed and used to generate A...
+
+### sus
+
+A fast and scalable test runner.
+
+#### [Using Sus Testing Framework](.context/sus/usage.md)
+
+Sus is a modern Ruby testing framework that provides a clean, BDD-style syntax for writing tests. It's designed to be fast, simple, and expressive.
+
+#### [Mocking](.context/sus/mocking.md)
+
+There are two types of mocking in sus: `receive` and `mock`. The `receive` matcher is a subset of full mocking and is used to set expectations on method calls, while `mock` can be used to replace m...
+
+#### [Shared Test Behaviors and Fixtures](.context/sus/shared.md)
+
+Sus provides shared test contexts which can be used to define common behaviours or tests that can be reused across one or more test files.

data/lib/async/barrier.md

@@ -1,6 +1,5 @@
 A synchronization primitive, which allows one task to wait for a number of other tasks to complete. It can be used in conjunction with {Semaphore}.
 
-
 ## Example
 
 ~~~ ruby

data/lib/async/barrier.rb

@@ -1,10 +1,11 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2024, by Samuel Williams.
+# Copyright, 2019-2025, by Samuel Williams.
 
 require_relative "list"
 require_relative "task"
+require_relative "queue"
 
 module Async
 	# A general purpose synchronisation primitive, which allows one task to wait for a number of other tasks to complete. It can be used in conjunction with {Semaphore}.
@@ -16,6 +17,7 @@ module Async
 		# @public Since *Async v1*.
 		def initialize(parent: nil)
 			@tasks = List.new
+			@finished = Queue.new
 			
 			@parent = parent
 		end
@@ -41,11 +43,15 @@ module Async
 		# Execute a child task and add it to the barrier.
 		# @asynchronous Executes the given block concurrently.
 		def async(*arguments, parent: (@parent or Task.current), **options, &block)
-			task = parent.async(*arguments, **options, &block)
+			waiting = nil
 			
-			@tasks.append(TaskNode.new(task))
-			
-			return task
+			parent.async(*arguments, **options) do |task, *arguments|
+				waiting = TaskNode.new(task)
+				@tasks.append(waiting)
+				block.call(task, *arguments)
+			ensure
+				@finished.signal(waiting)
+			end
 		end
 		
 		# Whether there are any tasks being held by the barrier.
@@ -55,14 +61,27 @@ module Async
 		end
 		
 		# Wait for all tasks to complete by invoking {Task#wait} on each waiting task, which may raise an error. As long as the task has completed, it will be removed from the barrier.
+		#
+		# @yields {|task| ...} If a block is given, the unwaited task is yielded. You must invoke {Task#wait} yourself. In addition, you may `break` if you have captured enough results.
+		#
 		# @asynchronous Will wait for tasks to finish executing.
 		def wait
-			@tasks.each do |waiting|
+			while !@tasks.empty?
+				# Wait for a task to finish (we get the task node):
+				return unless waiting = @finished.wait
+				
+				# Remove the task as it is now finishing:
+				@tasks.remove?(waiting)
+				
+				# Get the task:
 				task = waiting.task
-				begin
+				
+				# If a block is given, the user can implement their own behaviour:
+				if block_given?
+					yield task
+				else
+					# Wait for it to either complete or raise an error:
 					task.wait
-				ensure
-					@tasks.remove?(waiting) unless task.alive?
 				end
 			end
 		end
@@ -73,6 +92,8 @@ module Async
 			@tasks.each do |waiting|
 				waiting.task.stop
 			end
+			
+			@finished.close
 		end
 	end
 end

data/lib/async/clock.rb

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

data/lib/async/condition.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2017-2024, by Samuel Williams.
+# Copyright, 2017-2025, by Samuel Williams.
 # Copyright, 2017, by Kent Gruber.
 
 require "fiber"
@@ -42,6 +42,8 @@ module Async
 		
 		# @deprecated Replaced by {#waiting?}
 		def empty?
+			warn("`Async::Condition#empty?` is deprecated, use `Async::Condition#waiting?` instead.", uplevel: 1, category: :deprecated) if $VERBOSE
+			
 			@waiting.empty?
 		end
 		

data/lib/async/limited_queue.rb

@@ -1,7 +1,13 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2024, by Samuel Williams.
+# Copyright, 2025, by Samuel Williams.
 
 # The implementation lives in `queue.rb` but later we may move it here for better autoload/inference.
 require_relative "queue"
+
+module Async
+	class LimitedQueue < Queue
+		singleton_class.remove_method(:new)
+	end
+end

data/lib/async/list.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2022-2024, by Samuel Williams.
+# Copyright, 2022-2025, by Samuel Williams.
+# Copyright, 2025, by Shopify Inc.
 
 module Async
 	# A general doublely linked list. This is used internally by {Async::Barrier} and {Async::Condition} to manage child tasks.
@@ -18,6 +19,7 @@ module Async
 			sprintf("#<%s:0x%x size=%d>", self.class.name, object_id, @size)
 		end
 		
+		# @returns [String] A short summary of the list.
 		alias inspect to_s
 		
 		# Fast, safe, unbounded accumulation of children.
@@ -134,7 +136,7 @@ module Async
 			return removed(node)
 		end
 		
-		# @returns [Boolean] Returns true if the list is empty.
+		# @returns [Boolean] True if the list is empty.
 		def empty?
 			@size == 0
 		end
@@ -143,26 +145,26 @@ module Async
 		# 	previous = self
 		# 	current = @tail
 		# 	found = node.equal?(self)
-			
+		
 		# 	while true
 		# 		break if current.equal?(self)
-				
+		
 		# 		if current.head != previous
 		# 			raise "Invalid previous linked list node!"
 		# 		end
-				
+		
 		# 		if current.is_a?(List) and !current.equal?(self)
 		# 			raise "Invalid list in list node!"
 		# 		end
-				
+		
 		# 		if node
 		# 			found ||= current.equal?(node)
 		# 		end
-				
+		
 		# 		previous = current
 		# 		current = current.tail
 		# 	end
-			
+		
 		# 	if node and !found
 		# 		raise "Node not found in list!"
 		# 	end
@@ -238,6 +240,12 @@ module Async
 			attr_accessor :head
 			attr_accessor :tail
 			
+			# @returns [String] A string representation of the node.
+			def to_s
+				sprintf("#<%s:0x%x>", self.class.name, object_id)
+			end
+			
+			# @returns [String] A string representation of the node.
 			alias inspect to_s
 		end
 		

data/lib/async/node.rb

@@ -4,6 +4,7 @@
 # Copyright, 2017-2024, by Samuel Williams.
 # Copyright, 2017, by Kent Gruber.
 # Copyright, 2022, by Shannon Skipper.
+# Copyright, 2025, by Shopify Inc.
 
 require "fiber/annotation"
 
@@ -180,6 +181,7 @@ module Async
 			"\#<#{self.description}>"
 		end
 		
+		# @returns [String] A description of the node.
 		alias inspect to_s
 		
 		# Change the parent of this node.

data/lib/async/notification.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2018-2024, by Samuel Williams.
+# Copyright, 2018-2025, by Samuel Williams.
 
 require_relative "condition"
 
@@ -10,12 +10,14 @@ module Async
 	# @public Since *Async v1*.
 	class Notification < Condition
 		# Signal to a given task that it should resume operations.
+		#
+		# @returns [Boolean] if a task was signalled.
 		def signal(value = nil, task: Task.current)
-			return if @waiting.empty?
+			return false if @waiting.empty?
 			
 			Fiber.scheduler.push Signal.new(self.exchange, value)
 			
-			return nil
+			return true
 		end
 		
 		Signal = Struct.new(:waiting, :value) do

data/lib/async/queue.rb

@@ -1,9 +1,11 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2018-2024, by Samuel Williams.
+# Copyright, 2018-2025, by Samuel Williams.
 # Copyright, 2019, by Ryan Musgrave.
 # Copyright, 2020-2022, by Bruno Sutic.
+# Copyright, 2025, by Jahfer Husain.
+# Copyright, 2025, by Shopify Inc.
 
 require_relative "notification"
 
@@ -14,16 +16,31 @@ module Async
 	#
 	# @public Since *Async v1*.
 	class Queue
+		# An error raised when trying to enqueue items to a closed queue.
+		# @public Since *Async v2.24*.
+		class ClosedError < RuntimeError
+		end
+		
 		# Create a new queue.
 		#
 		# @parameter parent [Interface(:async) | Nil] The parent task to use for async operations.
 		# @parameter available [Notification] The notification to use for signaling when items are available.
 		def initialize(parent: nil, available: Notification.new)
 			@items = []
+			@closed = false
 			@parent = parent
 			@available = available
 		end
 		
+		# Close the queue, causing all waiting tasks to return `nil`. Any subsequent calls to {enqueue} will raise an exception.
+		def close
+			@closed = true
+			
+			while @available.waiting?
+				@available.signal(nil)
+			end
+		end
+		
 		# @attribute [Array] The items in the queue.
 		attr :items
 		
@@ -39,6 +56,10 @@ module Async
 		
 		# Add an item to the queue.
 		def push(item)
+			if @closed
+				raise ClosedError, "Cannot push items to a closed queue."
+			end
+			
 			@items << item
 			
 			@available.signal unless self.empty?
@@ -51,6 +72,10 @@ module Async
 		
 		# Add multiple items to the queue.
 		def enqueue(*items)
+			if @closed
+				raise ClosedError, "Cannot enqueue items to a closed queue."
+			end
+			
 			@items.concat(items)
 			
 			@available.signal unless self.empty?
@@ -59,6 +84,10 @@ module Async
 		# Remove and return the next item from the queue.
 		def dequeue
 			while @items.empty?
+				if @closed
+					return nil
+				end
+				
 				@available.wait
 			end
 			
@@ -105,6 +134,13 @@ module Async
 	# A queue which limits the number of items that can be enqueued.
 	# @public Since *Async v1*.
 	class LimitedQueue < Queue
+		# @private This exists purely for emitting a warning.
+		def self.new(...)
+			warn("`require 'async/limited_queue'` to use `Async::LimitedQueue`.", uplevel: 1, category: :deprecated) if $VERBOSE
+			
+			super
+		end
+		
 		# Create a new limited queue.
 		#
 		# @parameter limit [Integer] The maximum number of items that can be enqueued.
@@ -119,9 +155,19 @@ module Async
 		# @attribute [Integer] The maximum number of items that can be enqueued.
 		attr :limit
 		
+		# Close the queue, causing all waiting tasks to return `nil`. Any subsequent calls to {enqueue} will raise an exception.
+		# Also signals all tasks waiting for the queue to be full.
+		def close
+			super
+			
+			while @full.waiting?
+				@full.signal(nil)
+			end
+		end
+		
 		# @returns [Boolean] Whether trying to enqueue an item would block.
 		def limited?
-			@items.size >= @limit
+			!@closed && @items.size >= @limit
 		end
 		
 		# Add an item to the queue.
@@ -148,6 +194,10 @@ module Async
 					@full.wait
 				end
 				
+				if @closed
+					raise ClosedError, "Cannot enqueue items to a closed queue."
+				end
+				
 				available = @limit - @items.size
 				@items.concat(items.shift(available))
 				

data/lib/async/reactor.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2017-2024, by Samuel Williams.
+# Copyright, 2017-2025, by Samuel Williams.
 # Copyright, 2017, by Kent Gruber.
 # Copyright, 2018, by Sokolov Yura.
 
@@ -12,6 +12,8 @@ module Async
 	class Reactor < Scheduler
 		# @deprecated Replaced by {Kernel::Async}.
 		def self.run(...)
+			warn("`Async::Reactor.run{}` is deprecated, use `Async{}` instead.", uplevel: 1, category: :deprecated) if $VERBOSE
+			
 			Async(...)
 		end
 		

data/lib/async/scheduler.rb

@@ -1,14 +1,14 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2024, by Samuel Williams.
+# Copyright, 2020-2025, by Samuel Williams.
 # Copyright, 2020, by Jun Jiang.
 # Copyright, 2021, by Julien Portalier.
+# Copyright, 2025, by Shopify Inc.
 
 require_relative "clock"
 require_relative "task"
 require_relative "timeout"
-require_relative "worker_pool"
 
 require "io/event"
 
@@ -46,6 +46,28 @@ module Async
 			true
 		end
 		
+		# Used to augment the scheduler to add support for blocking operations.
+		module BlockingOperationWait
+			# Wait for the given work to be executed.
+			#
+			# @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.
+			# @returns [Object] The result of the work.
+			def blocking_operation_wait(work)
+				@worker_pool.call(work)
+			end
+		end
+		
+		private_constant :BlockingOperationWait
+		
+		if ::IO::Event.const_defined?(:WorkerPool)
+			WorkerPool = ::IO::Event::WorkerPool
+		else
+			WorkerPool = nil
+		end
+		
 		# Create a new scheduler.
 		#
 		# @public Since *Async v1*.
@@ -65,14 +87,15 @@ module Async
 			@idle_time = 0.0
 			
 			@timers = ::IO::Event::Timers.new
+			
 			if worker_pool == true
-				@worker_pool = WorkerPool.new
+				@worker_pool = WorkerPool&.new
 			else
 				@worker_pool = worker_pool
 			end
 			
 			if @worker_pool
-				self.singleton_class.prepend(WorkerPool::BlockingOperationWait)
+				self.singleton_class.prepend(BlockingOperationWait)
 			end
 		end
 		
@@ -97,7 +120,7 @@ module Async
 				return @busy_time / total_time
 			end
 		end
-	
+		
 		# Invoked when the fiber scheduler is being closed.
 		#
 		# Executes the run loop until all tasks are finished, then closes the scheduler.
@@ -234,7 +257,7 @@ module Async
 		# @parameter blocker [Object] The object that was blocking the fiber.
 		# @parameter fiber [Fiber] The fiber to unblock.
 		def unblock(blocker, fiber)
-			# $stderr.puts "unblock(#{blocker}, #{fiber})"
+			# Fiber.blocking{$stderr.puts "unblock(#{blocker}, #{fiber})"}
 			
 			# This operation is protected by the GVL:
 			if selector = @selector
@@ -250,6 +273,8 @@ module Async
 		#
 		# @parameter duration [Numeric | Nil] The time in seconds to sleep, or if nil, indefinitely.
 		def kernel_sleep(duration = nil)
+			# Fiber.blocking{$stderr.puts "kernel_sleep(#{duration}, #{Fiber.current})"}
+			
 			if duration
 				self.block(nil, duration)
 			else
@@ -348,6 +373,34 @@ module Async
 			end
 		end
 		
+		# Used to defer stopping the current task until later.
+		class FiberInterrupt
+			# Create a new stop later operation.
+			#
+			# @parameter task [Task] The task to stop later.
+			def initialize(fiber, exception)
+				@fiber = fiber
+				@exception = exception
+			end
+			
+			# @returns [Boolean] Whether the task is alive.
+			def alive?
+				@fiber.alive?
+			end
+			
+			# Transfer control to the operation - this will stop the task.
+			def transfer
+				# Fiber.blocking{$stderr.puts "FiberInterrupt#transfer(#{@fiber}, #{@exception})"}
+				@fiber.raise(@exception)
+			end
+		end
+		
+		# Raise an exception on the specified fiber, waking up the event loop if necessary.
+		def fiber_interrupt(fiber, exception)
+			# Fiber.blocking{$stderr.puts "fiber_interrupt(#{fiber}, #{exception})"}
+			unblock(nil, FiberInterrupt.new(fiber, exception))
+		end
+		
 		# Wait for the specified process ID to exit.
 		#
 		# @public Since *Async v2*.
@@ -361,6 +414,19 @@ module Async
 			return @selector.process_wait(Fiber.current, pid, flags)
 		end
 		
+		# Wait for the specified IOs to become ready for the specified events.
+		#
+		# @public Since *Async v2.25*.
+		# @asynchronous May be non-blocking.
+		def io_select(...)
+			Thread.new do
+				# Don't make unnecessary output, since we will propagate the exception:
+				Thread.current.report_on_exception = false
+				
+				::IO.select(...)
+			end.value
+		end
+		
 		# Run one iteration of the event loop.
 		#
 		# When terminating the event loop, we already know we are finished. So we don't need to check the task tree. This is a logical requirement because `run_once` ignores transient tasks. For example, a single top level transient task is not enough to keep the reactor running, but during termination we must still process it in order to terminate child tasks.
@@ -517,7 +583,7 @@ module Async
 		# @yields {|task| ...} Executed within the task.
 		# @returns [Task] The task that was scheduled into the reactor.
 		def async(*arguments, **options, &block)
-			# warn "Async::Scheduler#async is deprecated. Use `run` or `Task#async` instead.", uplevel: 1, category: :deprecated
+			warn("Async::Scheduler#async is deprecated. Use `run` or `Task#async` instead.", uplevel: 1, category: :deprecated) if $VERBOSE
 			
 			Kernel.raise ClosedError if @selector.nil?
 			
@@ -528,6 +594,8 @@ module Async
 			return task
 		end
 		
+		# Create a new fiber and return it without starting execution.
+		# @returns [Fiber] The fiber that was created.
 		def fiber(...)
 			return async(...).fiber
 		end

data/lib/async/stop.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require "fiber"
+require "console"
+
+module Async
+	# Raised when a task is explicitly stopped.
+	class Stop < Exception
+		# Represents the source of the stop operation.
+		class Cause < Exception
+			if RUBY_VERSION >= "3.4"
+				# @returns [Array(Thread::Backtrace::Location)] The backtrace of the caller.
+				def self.backtrace
+					caller_locations(2..-1)
+				end
+			else
+				# @returns [Array(String)] The backtrace of the caller.
+				def self.backtrace
+					caller(2..-1)
+				end
+			end
+			
+			# Create a new cause of the stop operation, with the given message.
+			#
+			# @parameter message [String] The error message.
+			# @returns [Cause] The cause of the stop operation.
+			def self.for(message = "Task was stopped")
+				instance = self.new(message)
+				instance.set_backtrace(self.backtrace)
+				return instance
+			end
+		end
+		
+		if RUBY_VERSION < "3.5"
+			# Create a new stop operation.
+			#
+			# This is a compatibility method for Ruby versions before 3.5 where cause is not propagated correctly when using {Fiber#raise}
+			#
+			# @parameter message [String | Hash] The error message or a hash containing the cause.
+			def initialize(message = "Task was stopped")
+				if message.is_a?(Hash)
+					@cause = message[:cause]
+					message = "Task was stopped"
+				end
+				
+				super(message)
+			end
+			
+			# @returns [Exception] The cause of the stop operation.
+			#
+			# This is a compatibility method for Ruby versions before 3.5 where cause is not propagated correctly when using {Fiber#raise}, we explicitly capture the cause here.
+			def cause
+				super || @cause
+			end
+		end
+		
+		# Used to defer stopping the current task until later.
+		class Later
+			# Create a new stop later operation.
+			#
+			# @parameter task [Task] The task to stop later.
+			# @parameter cause [Exception] The cause of the stop operation.
+			def initialize(task, cause = nil)
+				@task = task
+				@cause = cause
+			end
+			
+			# @returns [Boolean] Whether the task is alive.
+			def alive?
+				true
+			end
+			
+			# Transfer control to the operation - this will stop the task.
+			def transfer
+				@task.stop(false, cause: @cause)
+			end
+		end
+	end
+end