async 2.35.3 → 2.36.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7c439d8ba1591623b695ccd1dd4fe68f822fedd589291a7bdd79a53ce9c430d7
-  data.tar.gz: cc8902bc5b15f446df404967e1832c9847eb0bcad879565508f6688bd0a5c92a
+  metadata.gz: b514097c721290749f38fed73721c5cb6d17af2a8af189f5a8e537f7b30c14d3
+  data.tar.gz: 3eba30b0a03bdb9f9da1d1e4eeb6b11ec3224c0f3d02f27cc07ac1e5e7d7a41e
 SHA512:
-  metadata.gz: c2bfeb61c9f9ddad7576c66be0b637bee5934159e9388fe21cd0b1e8e5df804b5818194ef812d6249570411591d232a4c570fc6c6bcd02d67496e7aaf8950467
-  data.tar.gz: 2454b411f93e6e86e25030bdd358eba7ed38536928ab64dc64b1dc10e3dff152ac4005ad27bdf3d4e801c49d69c2b386f7ca08961d90015dbe86fa2e9bccc5cf
+  metadata.gz: 9ea8d371279ec9bf8feeaa85895f25733247c8ecb059d599f34e8ecc85b4b124c05dee5421414d28c24316d7c4e69bdff622c31b182e9f883456836a6aab17ed
+  data.tar.gz: 55ddefa4f011c2dccf235043cad5ad334418c394ced59a960b993d18ead0850f7d60875a3edbdc55418d3a9d3045cef1d607170fea0ae484f4dc62bc13f15ca2

data/lib/async/node.rb

@@ -295,6 +295,12 @@ module Async
 			end
 		end
 		
+		# Wait for this node to complete. By default, nodes cannot be waited on.
+		# Subclasses like Task override this method to provide waiting functionality.
+		def wait
+			nil
+		end
+		
 		# Whether the node has been stopped.
 		def stopped?
 			@children.nil?

data/lib/async/task.rb

@@ -31,6 +31,32 @@ module Async
 		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
+	# 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 Creating a task that sleeps for 1 second.
+	# 	require "async"
+	# 	Async do |task|
+	# 		sleep(1)
+	# 	end
+	#
 	# @public Since *Async v1*.
 	class Task < Node
 		# Raised when a child task is created within a task that has finished execution.
@@ -258,11 +284,43 @@ module Async
 			begin
 				@promise.wait
 			rescue Promise::Cancel
-				# For backward compatibility, stopped tasks return nil
+				# For backward compatibility, stopped tasks return nil:
 				return nil
 			end
 		end
 		
+		# For compatibility with `Thread#join` and similar interfaces.
+		alias join wait
+		
+		# Wait on all non-transient children to complete, recursively, then wait on the task itself, if it is not the current task.
+		#
+		# If any child task fails with an exception, that exception will be raised immediately, and remaining children may not be waited on.
+		#
+		# @example Waiting on all children.
+		# 	Async do |task|
+		# 		child = task.async do
+		# 			sleep(0.01)
+		# 		end
+		# 		task.wait_all # Will wait on the child task.
+		# 	end
+		#
+		# @raises [StandardError] If any child task failed with an exception, that exception will be raised.
+		# @returns [Object | Nil] The final expression/result of the task's block, or nil if called from within the task.
+		# @asynchronous This method is thread-safe.
+		def wait_all
+			@children&.each do |child|
+				# Skip transient tasks
+				next if child.transient?
+				
+				child.wait_all
+			end
+			
+			# Only wait on the task if we're not waiting on ourselves:
+			unless self.current?
+				return self.wait
+			end
+		end
+		
 		# Access the result of the task without waiting. May be nil if the task is not completed. Does not raise exceptions.
 		def result
 			value = @promise.value

data/lib/async/version.rb

@@ -4,5 +4,5 @@
 # Copyright, 2017-2025, by Samuel Williams.
 
 module Async
-	VERSION = "2.35.3"
+	VERSION = "2.36.0"
 end

data/readme.md

@@ -35,6 +35,11 @@ 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.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.
@@ -72,13 +77,6 @@ Please see the [project releases](https://socketry.github.io/async/releases/inde
 
   - Introduce `Async::Deadline` for precise timeout management in compound operations.
 
-### v2.30.0
-
-  - Add timeout support to `Async::Queue#dequeue` and `Async::Queue#pop` methods.
-  - Add timeout support to `Async::PriorityQueue#dequeue` and `Async::PriorityQueue#pop` methods.
-  - Add `closed?` method to `Async::PriorityQueue` for full queue interface compatibility.
-  - Support non-blocking operations using `timeout: 0` parameter.
-
 ## See Also
 
   - [async-http](https://github.com/socketry/async-http) — Asynchronous HTTP client/server.

data/releases.md

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async
 version: !ruby/object:Gem::Version
-  version: 2.35.3
+  version: 2.36.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -175,7 +175,6 @@ 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

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
-```