async 2.24.0 → 2.26.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 95c1315007ff80d78bdd1538d2b2963ed951db5aa92906ea6f22560612540cbc
-  data.tar.gz: 03ffadcf7c2523827bd6c49340df0a846f8ab3214593d897b4359b548a765cef
+  metadata.gz: 9c593ddf06be9954e63b4f85eb8c0fe022be6cf1e241a37f86620a82fdf860b3
+  data.tar.gz: 023b1544a36d3bb8ff85f0b8cc3ccc0b4694ed3b0542ed7dafd02330f05ee663
 SHA512:
-  metadata.gz: 62c15e0c19e7f3277ca9e4981b0304d5f039367fb0d6b996a8c562be170b3436f66e97f33fcfd5eb0ed8ec84e760ae2b565a022604e026f3b2c797613534fd59
-  data.tar.gz: 79c7148d35f3e06243b3845721b8a1ebcf5fd2e6244eab18ac5a0f42894088334df307c4da52d9d9c59b0d9499e457f0990022d570abf109202416cf168211a1
+  metadata.gz: 65c3fee1ef33362307c4c74dd2451384de1e1747041ffd68cec0049465a317dada93083198254b905e89758a112800894436fe4cc8a2c713b0c0f5de1a36402e
+  data.tar.gz: a90fa15643b4a491599e95429c0d79da4363d0778455a50893ee9d6f34217ebd442bf99085f981807e024dfec561f545ea86d74e06f2874b34c1bd191a1b79fa

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

@@ -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,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2022-2024, by Samuel Williams.
+# Copyright, 2022-2025, by Samuel Williams.
 
 module Async
 	# A general doublely linked list. This is used internally by {Async::Barrier} and {Async::Condition} to manage child tasks.
@@ -18,6 +18,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 +135,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
@@ -238,6 +239,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

@@ -180,6 +180,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,10 @@
 # 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.
 
 require_relative "notification"
 
@@ -14,16 +15,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 +55,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 +71,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 +83,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 +133,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 +154,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 +193,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

@@ -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"
 
@@ -45,7 +45,29 @@ module Async
 		def self.supported?
 			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
 		
@@ -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/task.rb

@@ -1,11 +1,12 @@
 # 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, 2017, by Devin Christensen.
 # Copyright, 2020, by Patrik Wenger.
 # Copyright, 2023, by Math Ieu.
+# Copyright, 2025, by Shigeru Nakajima.
 
 require "fiber"
 require "console"
@@ -64,6 +65,8 @@ module Async
 		
 		# @deprecated With no replacement.
 		def self.yield
+			warn("`Async::Task.yield` is deprecated with no replacement.", uplevel: 1, category: :deprecated) if $VERBOSE
+			
 			Fiber.scheduler.transfer
 		end
 		
@@ -133,6 +136,8 @@ module Async
 		
 		# @deprecated Prefer {Kernel#sleep} except when compatibility with `stable-v1` is required.
 		def sleep(duration = nil)
+			Kernel.warn("`Async::Task#sleep` is deprecated, use `Kernel#sleep` instead.", uplevel: 1, category: :deprecated) if $VERBOSE
+			
 			super
 		end
 		

data/lib/async/variable.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2021-2024, by Samuel Williams.
+# Copyright, 2021-2025, by Samuel Williams.
 
 require_relative "condition"
 

data/lib/async/version.rb

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

data/lib/async/waiter.rb

@@ -6,12 +6,15 @@
 
 module Async
 	# A composable synchronization primitive, which allows one task to wait for a number of other tasks to complete. It can be used in conjunction with {Semaphore} and/or {Barrier}.
+	# @deprecated `Async::Waiter` is deprecated, use `Async::Barrier` instead. 
 	class Waiter
 		# Create a waiter instance.
 		#
 		# @parameter parent [Interface(:async) | Nil] The parent task to use for asynchronous operations.
 		# @parameter finished [Async::Condition] The condition to signal when a task completes.
 		def initialize(parent: nil, finished: Async::Condition.new)
+			warn("`Async::Waiter` is deprecated, use `Async::Barrier` instead.", uplevel: 1, category: :deprecated) if $VERBOSE
+			
 			@finished = finished
 			@done = []
 			

data/lib/metrics/provider/async/task.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2024, by Samuel Williams.
+# Copyright, 2024-2025, by Samuel Williams.
 
 require_relative "../../../async/task"
 require "metrics/provider"

data/lib/traces/provider/async/barrier.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2022, by Samuel Williams.
+# Copyright, 2024-2025, by Samuel Williams.
 
 require_relative "../../../async/barrier"
 require "traces/provider"

data/lib/traces/provider/async/task.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2022, by Samuel Williams.
+# Copyright, 2024-2025, by Samuel Williams.
 
 require_relative "../../../async/task"
 require "traces/provider"

data/license.md

@@ -1,6 +1,6 @@
 # MIT License
 
-Copyright, 2017-2024, by Samuel Williams.  
+Copyright, 2017-2025, by Samuel Williams.  
 Copyright, 2017, by Kent Gruber.  
 Copyright, 2017, by Devin Christensen.  
 Copyright, 2018, by Sokolov Yura.  
@@ -27,6 +27,11 @@ Copyright, 2023, by Emil Tin.
 Copyright, 2023, by Gert Goet.  
 Copyright, 2024, by Dimitar Peychinov.  
 Copyright, 2024, by Jamie McCarthy.  
+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.  
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/readme.md

@@ -35,6 +35,23 @@ 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.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)
+
 ### v2.24.0
 
   - Ruby v3.1 support is dropped.
@@ -56,7 +73,7 @@ Please see the [project releases](https://socketry.github.io/async/releases/inde
 
 ### v2.19.0
 
-  - [Async::Scheduler Debugging](https://socketry.github.io/async/releases/index#async::scheduler-debugging)
+  - [`Async::Scheduler` Debugging](https://socketry.github.io/async/releases/index#async::scheduler-debugging)
   - [Console Shims](https://socketry.github.io/async/releases/index#console-shims)
 
 ### v2.18.0

data/releases.md

@@ -1,5 +1,114 @@
 # Releases
 
+## 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
+
+`Async::Barrier` now provides more flexible and predictable behavior for waiting on task completion:
+
+  - **Completion-order waiting**: `barrier.wait` now processes tasks in the order they complete rather than the order they were created. This provides more predictable behavior when tasks have different execution times.
+  - **Block-based waiting**: `barrier.wait` now accepts an optional block that yields each task as it completes, allowing for custom handling of individual tasks:
+
+<!-- end list -->
+
+``` ruby
+barrier = Async::Barrier.new
+
+# Start several tasks
+3.times do |i|
+	barrier.async do |task|
+		sleep(rand * 0.1)  # Random completion time
+		"result_#{i}"
+	end
+end
+
+# Wait for all tasks, processing them as they complete
+barrier.wait do |task|
+	result = task.wait
+	puts "Task completed with: #{result}"
+end
+```
+
+  - **Partial completion support**: The new block-based interface allows you to wait for only the first N tasks to complete:
+
+<!-- end list -->
+
+``` ruby
+# Wait for only the first 3 tasks to complete
+count = 0
+barrier.wait do |task|
+	task.wait
+	count += 1
+	break if count >= 3
+end
+```
+
+This makes `Async::Barrier` a superset of `Async::Waiter` functionality, providing more flexible task coordination patterns, and therrefore, `Async::Waiter` is now deprecated.
+
+### Introduce `Async::Queue#close`
+
+`Async::Queue` and `Async::LimitedQueue` can now be closed, which provides better resource management and error handling:
+
+  - **New `close` method**: Both queue types now have a `close` method that prevents further items from being added and signals any waiting tasks.
+  - **Consistent error handling**: All queue modification methods (`push`, `enqueue`, `<<`) now raise `Async::Queue::ClosedError` when called on a closed queue.
+  - **Waiting task signaling**: When a queue is closed, any tasks waiting on `dequeue` (for regular queues) or `enqueue` (for limited queues) are properly signaled and can complete.
+
+<!-- end list -->
+
+``` ruby
+queue = Async::Queue.new
+
+# Start a task waiting for items:
+waiting_task = Async do
+	queue.dequeue
+end
+
+# Close the queue - this signals the waiting task
+queue.close
+
+# These will raise Async::Queue::ClosedError
+queue.push(:item)      # => raises ClosedError
+queue.enqueue(:item)   # => raises ClosedError
+queue << :item         # => raises ClosedError
+
+# Dequeue returns nil when closed and empty
+queue.dequeue          # => nil
+```
+
+## 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
+
+The `Async::WorkerPool` implementation has been removed in favor of using `IO::Event::WorkerPool` directly. This change simplifies the codebase by delegating worker pool functionality to the `io-event` gem, which provides a more efficient and well-tested implementation.
+
+To enable the worker pool, you can set the `ASYNC_SCHEDULER_WORKER_POOL` environment variable to `true`. This will allow the scheduler to use a worker pool for blocking operations, which can help improve performance in applications that perform a lot of CPU-bound operations (e.g. `rb_nogvl`).
+
+### Better handling of `IO#close` using `fiber_interrupt`
+
+`IO#close` interrupts fibers that are waiting on the IO using the new `fiber_interrupt` hook introduced in Ruby 3.5/4.0. This means that if you close an IO while a fiber is waiting on it, the fiber will be interrupted and will raise an `IOError`. This is a change from previous versions of Ruby, where closing an IO would not interrupt fibers waiting on it, and would instead interrupt the entire event loop (essentially a bug).
+
+``` ruby
+r, w = IO.pipe
+
+Async do
+	child = Async do
+		r.gets
+	end
+	
+	r.close # This will interrupt the child fiber.
+	child.wait # This will raise an `IOError` because the IO was closed.
+end
+```
+
 ## v2.24.0
 
   - Ruby v3.1 support is dropped.
@@ -7,7 +116,7 @@
 
 ### Flexible Timeouts
 
-When {ruby Async::Scheduler\#with\_timeout} is invoked with a block, it can receive a {ruby Async::Timeout} instance. This allows you to adjust or cancel the timeout while the block is executing. This is useful for long-running tasks that may need to adjust their timeout based on external factors.
+When `Async::Scheduler#with_timeout` is invoked with a block, it can receive a `Async::Timeout` instance. This allows you to adjust or cancel the timeout while the block is executing. This is useful for long-running tasks that may need to adjust their timeout based on external factors.
 
 ``` ruby
 Async do
@@ -81,7 +190,7 @@ To take advantage of this feature, you will need to introduce your own `config/t
 
 ## v2.19.0
 
-### Async::Scheduler Debugging
+### `Async::Scheduler` Debugging
 
 Occasionally on issues, I encounter people asking for help and I need more information. Pressing Ctrl-C to exit a hung program is common, but it usually doesn't provide enough information to diagnose the problem. Setting the `CONSOLE_LEVEL=debug` environment variable will now print additional information about the scheduler when you interrupt it, including a backtrace of the current tasks.
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async
 version: !ruby/object:Gem::Version
-  version: 2.24.0
+  version: 2.26.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -10,24 +10,29 @@ authors:
 - Olle Jonsson
 - Patrik Wenger
 - Devin Christensen
+- Shopify Inc.
 - Emil Tin
 - Jamie McCarthy
 - Kent Gruber
+- Alan Wu
 - Brian Morearty
 - Colin Kelley
 - Dimitar Peychinov
 - Gert Goet
+- Jahfer Husain
 - Jiang Jinyang
 - Julien Portalier
 - Jun Jiang
 - Ken Muryoi
 - Leon Löchner
+- Mark Montroy
 - Masafumi Okura
 - Masayuki Yamamoto
 - Math Ieu
 - Ryan Musgrave
 - Salim Semaoune
 - Shannon Skipper
+- Shigeru Nakajima
 - Sokolov Yura
 - Stefan Wrobel
 - Trevor Turk
@@ -62,7 +67,7 @@ cert_chain:
   Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
   voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
   -----END CERTIFICATE-----
-date: 2025-05-03 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: console
@@ -98,46 +103,47 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.9'
+        version: '1.12'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.9'
+        version: '1.12'
 - !ruby/object:Gem::Dependency
-  name: traces
+  name: metrics
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.15'
+        version: '0.12'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.15'
+        version: '0.12'
 - !ruby/object:Gem::Dependency
-  name: metrics
+  name: traces
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.12'
+        version: '0.15'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.12'
+        version: '0.15'
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- agent.md
 - lib/async.rb
 - lib/async/barrier.md
 - lib/async/barrier.rb
@@ -160,9 +166,7 @@ files:
 - lib/async/timeout.rb
 - lib/async/variable.rb
 - lib/async/version.rb
-- lib/async/waiter.md
 - lib/async/waiter.rb
-- lib/async/worker_pool.rb
 - lib/kernel/async.rb
 - lib/kernel/sync.rb
 - lib/metrics/provider/async.rb
@@ -187,14 +191,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.1'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 3.6.7
 specification_version: 4
 summary: A concurrency framework for Ruby.
 test_files: []

data/lib/async/waiter.md

@@ -1,50 +0,0 @@
-A synchronization primitive, which allows you to wait for tasks to complete in order of completion. This is useful for implementing a task pool, where you want to wait for the first task to complete, and then cancel the rest.
-
-If you try to wait for more things than you have added, you will deadlock.
-
-## Example
-
-~~~ ruby
-require 'async'
-require 'async/semaphore'
-require 'async/barrier'
-require 'async/waiter'
-
-Sync do
-	barrier = Async::Barrier.new
-	waiter = Async::Waiter.new(parent: barrier)
-	semaphore = Async::Semaphore.new(2, parent: waiter)
-	
-	# Sleep sort the numbers:
-	generator = Async do
-		while true
-			semaphore.async do |task|
-				number = rand(1..10)
-				sleep(number)
-			end
-		end
-	end
-	
-	numbers = []
-	
-	4.times do
-		# Wait for all the numbers to be sorted:
-		numbers << waiter.wait
-	end
-	
-	# Don't generate any more numbers:
-	generator.stop
-	
-	# Stop all tasks which we don't care about:
-	barrier.stop
-	
-	Console.info("Smallest", numbers)
-end
-~~~
-
-### Output
-
-~~~
-0.0s     info: Smallest
-             | [3, 3, 1, 2]
-~~~

data/lib/async/worker_pool.rb

@@ -1,182 +0,0 @@
-# frozen_string_literal: true
-
-# Released under the MIT License.
-# Copyright, 2024, by Samuel Williams.
-
-require "etc"
-
-module Async
-	# A simple work pool that offloads work to a background thread.
-	#
-	# @private
-	class WorkerPool
-		# 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
-		
-		# Execute the given work in a background thread.
-		class Promise
-			# Create a new promise.
-			#
-			# @parameter work [Proc] The work to be done.
-			def initialize(work)
-				@work = work
-				@state = :pending
-				@value = nil
-				@guard = ::Mutex.new
-				@condition = ::ConditionVariable.new
-				@thread = nil
-			end
-			
-			# Execute the work and resolve the promise.
-			def call
-				work = nil
-				
-				@guard.synchronize do
-					@thread = ::Thread.current
-					
-					return unless work = @work
-				end
-				
-				resolve(work.call)
-			rescue Exception => error
-				reject(error)
-			end
-			
-			private def resolve(value)
-				@guard.synchronize do
-					@work = nil
-					@thread = nil
-					@value = value
-					@state = :resolved
-					@condition.broadcast
-				end
-			end
-			
-			private def reject(error)
-				@guard.synchronize do
-					@work = nil
-					@thread = nil
-					@value = error
-					@state = :failed
-					@condition.broadcast
-				end
-			end
-			
-			# Cancel the work and raise an exception in the background thread.
-			def cancel
-				return unless @work
-				
-				@guard.synchronize do
-					@work = nil
-					@state = :cancelled
-					@thread&.raise(Interrupt)
-				end
-			end
-			
-			# Wait for the work to be done.
-			#
-			# @returns [Object] The result of the work.
-			def wait
-				@guard.synchronize do
-					while @state == :pending
-						@condition.wait(@guard)
-					end
-					
-					if @state == :failed
-						raise @value
-					else
-						return @value
-					end
-				end
-			end
-		end
-		
-		# A background worker thread.
-		class Worker
-			# Create a new worker.
-			def initialize
-				@work = ::Thread::Queue.new
-				@thread = ::Thread.new(&method(:run))
-			end
-			
-			# Execute work until the queue is closed.
-			def run
-				while work = @work.pop
-					work.call
-				end
-			end
-			
-			# Close the worker thread.
-			def close
-				if thread = @thread
-					@thread = nil
-					thread.kill
-				end
-			end
-			
-			# Call the work and notify the scheduler when it is done.
-			def call(work)
-				promise = Promise.new(work)
-				
-				@work.push(promise)
-				
-				begin
-					return promise.wait
-				ensure
-					promise.cancel
-				end
-			end
-		end
-		
-		# Create a new work pool.
-		#
-		# @parameter size [Integer] The number of threads to use.
-		def initialize(size: Etc.nprocessors)
-			@ready = ::Thread::Queue.new
-			
-			size.times do
-				@ready.push(Worker.new)
-			end
-		end
-		
-		# Close the work pool. Kills all outstanding work.
-		def close
-			if ready = @ready
-				@ready = nil
-				ready.close
-				
-				while worker = ready.pop
-					worker.close
-				end
-			end
-		end
-		
-		# Offload work to a thread.
-		#
-		# @parameter work [Proc] The work to be done.
-		def call(work)
-			if ready = @ready
-				worker = ready.pop
-				
-				begin
-					worker.call(work)
-				ensure
-					ready.push(worker)
-				end
-			else
-				raise RuntimeError, "No worker available!"
-			end
-		end
-	end
-end