async 2.32.0 → 2.39.0

data/releases.md

@@ -1,5 +1,76 @@
 # Releases
 
+## v2.39.0
+
+  - `Async::Barrier#wait` now returns the number of tasks that were waited for, or `nil` if there were no tasks to wait for. This provides better feedback about the operation, and allows you to know how many tasks were involved in the wait.
+
+## v2.38.1
+
+  - Fix `Barrier#async` when `parent.async` yields before the child block executes. Previously, `Barrier#wait` could return early and miss tracking the task entirely, because the task had not yet appended itself to the barrier's task list.
+
+## v2.38.0
+
+  - Rename `Task#stop` to `Task#cancel` for better clarity and consistency with common concurrency terminology. The old `stop` method is still available as an alias for backward compatibility, but it is recommended to use `cancel` going forward.
+  - Forward arguments from `Task#wait` -\> `Promise#wait`, so `task.wait(timeout: N)` is supported.
+
+## v2.37.0
+
+  - Introduce `Async::Loop` for robust, time-aligned loops.
+  - Add support for `Async::Promise#wait(timeout: N)`.
+
+## v2.36.0
+
+  - Introduce `Task#wait_all` which recursively waits for all children and self, excepting the current task.
+  - Introduce `Task#join` as an alias for `Task#wait` for compatibility with `Thread#join` and similar interfaces.
+
+## v2.35.3
+
+  - `Async::Clock` now implements `#as_json` and `#to_json` for nicer log formatting.
+
+## v2.35.2
+
+  - Improved handling of `Process.fork` on Ruby 4+.
+  - Improve `@promise` state handling in `Task#initialize`, preventing incomplete instances being visible to the scheduler.
+
+## v2.35.1
+
+  - Fix incorrect handling of spurious wakeups in `Async::Promise#wait`, which could lead to premature (incorrect) resolution of the promise.
+
+## v2.35.0
+
+  - `Process.fork` is now properly handled by the Async fiber scheduler, ensuring that the scheduler state is correctly reset in the child process after a fork. This prevents issues where the child process inherits the scheduler state from the parent, which could lead to unexpected behavior.
+
+## v2.34.0
+
+### `Kernel::Barrier` Convenience Interface
+
+Starting multiple concurrent tasks and waiting for them to finish is a common pattern. This change introduces a small ergonomic helper, `Barrier`, defined in `Kernel`, that encapsulates this behavior: it creates an `Async::Barrier`, yields it to a block, waits for completion (using `Sync` to run a reactor if needed), and ensures remaining tasks are stopped on exit.
+
+``` ruby
+require "async"
+
+Barrier do |barrier|
+	3.times do |i|
+		barrier.async do |task|
+			sleep(rand * 0.1)  # Simulate work
+			puts "Task #{i} completed"
+		end
+	end
+end
+
+# All tasks are guaranteed to complete or be stopped when the block exits.
+```
+
+If an exception is raised by a task, it will be propagated to the caller, and any remaining tasks will be stopped. The `parent:` parameter can be used to specify a parent task for the barrier, otherwise it will use the current task if available, or create a new reactor if not.
+
+## v2.33.0
+
+  - Introduce `Async::Promise.fulfill` for optional promise resolution.
+
+## v2.32.1
+
+  - Fix typo in documentation.
+
 ## v2.32.0
 
   - Introduce `Queue#waiting_count` and `PriorityQueue#waiting_count`. Generally for statistics/testing purposes only.
@@ -35,15 +106,15 @@ This release introduces the new `Async::Promise` class and refactors `Async::Tas
 <!-- end list -->
 
 ``` ruby
-require 'async/promise'
+require "async/promise"
 
 # Basic promise usage - works independently of Async framework
 promise = Async::Promise.new
 
 # In another thread or fiber, resolve the promise
 Thread.new do
-  sleep(1)  # Simulate some work
-  promise.resolve("Hello, World!")
+	sleep(1)  # Simulate some work
+	promise.resolve("Hello, World!")
 end
 
 # Wait for the result
@@ -62,34 +133,34 @@ Promises bridge Thread and Fiber concurrency models - a promise resolved in one
 The new `Async::PriorityQueue` provides a thread-safe, fiber-aware queue where consumers can specify priority levels. Higher priority consumers are served first when items become available, with FIFO ordering maintained for equal priorities. This is useful for implementing priority-based task processing systems where critical operations need to be handled before lower priority work.
 
 ``` ruby
-require 'async'
-require 'async/priority_queue'
+require "async"
+require "async/priority_queue"
 
 Async do
-  queue = Async::PriorityQueue.new
-  
-  # Start consumers with different priorities
-  low_priority = async do
-    puts "Low priority consumer got: #{queue.dequeue(priority: 1)}"
-  end
-  
-  medium_priority = async do
-    puts "Medium priority consumer got: #{queue.dequeue(priority: 5)}"
-  end
-  
-  high_priority = async do
-    puts "High priority consumer got: #{queue.dequeue(priority: 10)}"
-  end
-  
-  # Add items to the queue
-  queue.push("first item")
-  queue.push("second item")
-  queue.push("third item")
-  
-  # Output:
-  # High priority consumer got: first item
-  # Medium priority consumer got: second item  
-  # Low priority consumer got: third item
+	queue = Async::PriorityQueue.new
+	
+		# Start consumers with different priorities
+	low_priority = async do
+		puts "Low priority consumer got: #{queue.dequeue(priority: 1)}"
+	end
+	
+	medium_priority = async do
+		puts "Medium priority consumer got: #{queue.dequeue(priority: 5)}"
+	end
+	
+	high_priority = async do
+		puts "High priority consumer got: #{queue.dequeue(priority: 10)}"
+	end
+	
+		# Add items to the queue
+	queue.push("first item")
+	queue.push("second item")
+	queue.push("third item")
+	
+		# Output:
+		# High priority consumer got: first item
+		# Medium priority consumer got: second item  
+		# Low priority consumer got: third item
 end
 ```
 
@@ -339,10 +410,10 @@ This gives better visibility into what the scheduler is doing, and should help d
 The `async` gem depends on `console` gem, because my goal was to have good logging by default without thinking about it too much. However, some users prefer to avoid using the `console` gem for logging, so I've added an experimental set of shims which should allow you to bypass the `console` gem entirely.
 
 ``` ruby
-require 'async/console'
-require 'async'
+require "async/console"
+require "async"
 
-Async{raise "Boom"}
+Async {raise "Boom"}
 ```
 
 Will now use `Kernel#warn` to print the task failure warning:
@@ -376,7 +447,7 @@ reactor = Async::Reactor.new # internally calls Fiber.set_scheduler
 
 # This should run in the above reactor, rather than creating a new one.
 Async do
-  puts "Hello World"
+	puts "Hello World"
 end
 ```
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async
 version: !ruby/object:Gem::Version
-  version: 2.32.0
+  version: 2.39.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -37,7 +37,9 @@ authors:
 - Shigeru Nakajima
 - Sokolov Yura
 - Stefan Wrobel
+- Tavian Barnes
 - Trevor Turk
+- Yuhi Sato
 bindir: bin
 cert_chain:
 - |
@@ -155,14 +157,18 @@ files:
 - lib/async.rb
 - lib/async/barrier.md
 - lib/async/barrier.rb
+- lib/async/cancel.rb
 - lib/async/clock.rb
 - lib/async/condition.md
 - 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
@@ -173,13 +179,13 @@ files:
 - lib/async/semaphore.md
 - lib/async/semaphore.rb
 - lib/async/stop.rb
-- lib/async/task.md
 - lib/async/task.rb
 - lib/async/timeout.rb
 - lib/async/variable.rb
 - lib/async/version.rb
 - lib/async/waiter.rb
 - lib/kernel/async.rb
+- lib/kernel/barrier.rb
 - lib/kernel/sync.rb
 - lib/metrics/provider/async.rb
 - lib/metrics/provider/async/task.rb
@@ -203,7 +209,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.2'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="

data/lib/async/task.md

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