async 2.24.0 → 2.27.0

data/lib/async/task.rb

@@ -1,44 +1,23 @@
 # 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"
 
 require_relative "node"
 require_relative "condition"
+require_relative "stop"
 
 Fiber.attr_accessor :async_task
 
 module Async
-	# Raised when a task is explicitly stopped.
-	class Stop < Exception
-		# 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.
-			def initialize(task)
-				@task = task
-			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
-			end
-		end
-	end
-	
 	# Raised if a timeout occurs on a specific Fiber. Handled gracefully by `Task`.
 	# @public Since *Async v1*.
 	class TimeoutError < StandardError
@@ -64,6 +43,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 +114,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
 		
@@ -266,7 +249,13 @@ module Async
 		# If `later` is false, it means that `stop` has been invoked directly. When `later` is true, it means that `stop` is invoked by `stop_children` or some other indirect mechanism. In that case, if we encounter the "current" fiber, we can't stop it right away, as it's currently performing `#stop`. Stopping it immediately would interrupt the current stop traversal, so we need to schedule the stop to occur later.
 		#
 		# @parameter later [Boolean] Whether to stop the task later, or immediately.
-		def stop(later = false)
+		# @parameter cause [Exception] The cause of the stop operation.
+		def stop(later = false, cause: $!)
+			# If no cause is given, we generate one from the current call stack:
+			unless cause
+				cause = Stop::Cause.for("Stopping task!")
+			end
+			
 			if self.stopped?
 				# If the task is already stopped, a `stop` state transition re-enters the same state which is a no-op. However, we will also attempt to stop any running children too. This can happen if the children did not stop correctly the first time around. Doing this should probably be considered a bug, but it's better to be safe than sorry.
 				return stopped!
@@ -280,7 +269,7 @@ module Async
 				# If we are deferring stop...
 				if @defer_stop == false
 					# Don't stop now... but update the state so we know we need to stop later.
-					@defer_stop = true
+					@defer_stop = cause
 					return false
 				end
 				
@@ -288,19 +277,19 @@ module Async
 					# If the fiber is current, and later is `true`, we need to schedule the fiber to be stopped later, as it's currently invoking `stop`:
 					if later
 						# If the fiber is the current fiber and we want to stop it later, schedule it:
-						Fiber.scheduler.push(Stop::Later.new(self))
+						Fiber.scheduler.push(Stop::Later.new(self, cause))
 					else
 						# Otherwise, raise the exception directly:
-						raise Stop, "Stopping current task!"
+						raise Stop, "Stopping current task!", cause: cause
 					end
 				else
 					# If the fiber is not curent, we can raise the exception directly:
 					begin
 						# There is a chance that this will stop the fiber that originally called stop. If that happens, the exception handling in `#stopped` will rescue the exception and re-raise it later.
-						Fiber.scheduler.raise(@fiber, Stop)
+						Fiber.scheduler.raise(@fiber, Stop, cause: cause)
 					rescue FiberError
 						# In some cases, this can cause a FiberError (it might be resumed already), so we schedule it to be stopped later:
-						Fiber.scheduler.push(Stop::Later.new(self))
+						Fiber.scheduler.push(Stop::Later.new(self, cause))
 					end
 				end
 			else
@@ -340,7 +329,7 @@ module Async
 					
 					# If we were asked to stop, we should do so now:
 					if defer_stop
-						raise Stop, "Stopping current task (was deferred)!"
+						raise Stop, "Stopping current task (was deferred)!", cause: defer_stop
 					end
 				end
 			else
@@ -351,7 +340,7 @@ module Async
 		
 		# @returns [Boolean] Whether stop has been deferred.
 		def stop_deferred?
-			@defer_stop
+			!!@defer_stop
 		end
 		
 		# Lookup the {Task} for the current fiber. Raise `RuntimeError` if none is available.

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.27.0"
 end

data/lib/async/waiter.rb

@@ -1,17 +1,20 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2022-2024, by Samuel Williams.
+# Copyright, 2022-2025, by Samuel Williams.
 # Copyright, 2024, by Patrik Wenger.
 
 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,28 @@ 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.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)
+
+### 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 +78,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
@@ -67,10 +89,6 @@ Please see the [project releases](https://socketry.github.io/async/releases/inde
 
   - Introduce `Async::Queue#push` and `Async::Queue#pop` for compatibility with `::Queue`.
 
-### v2.16.0
-
-  - [Better Handling of Async and Sync in Nested Fibers](https://socketry.github.io/async/releases/index#better-handling-of-async-and-sync-in-nested-fibers)
-
 ## See Also
 
   - [async-http](https://github.com/socketry/async-http) — Asynchronous HTTP client/server.

data/releases.md

@@ -1,5 +1,119 @@
 # Releases
 
+## 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
+
+`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 +121,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 +195,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,10 +1,11 @@
 --- !ruby/object:Gem::Specification
 name: async
 version: !ruby/object:Gem::Version
-  version: 2.24.0
+  version: 2.27.0
 platform: ruby
 authors:
 - Samuel Williams
+- Shopify Inc.
 - Bruno Sutic
 - Jeremy Jung
 - Olle Jonsson
@@ -13,21 +14,25 @@ authors:
 - 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.11'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.9'
+        version: '1.11'
 - !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
@@ -155,14 +161,13 @@ files:
 - lib/async/scheduler.rb
 - 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
 - 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 +192,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]
-~~~