async 2.35.2 → 2.36.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 28fcbed588ccb0c02ebed08bfc2d316b07e34563cb52fc639f33d5146c7ca9bc
-  data.tar.gz: b9319321c6acb3a6d48b0e76a2afbc3c017586855c6c842950eb0376db8b1bbb
+  metadata.gz: b514097c721290749f38fed73721c5cb6d17af2a8af189f5a8e537f7b30c14d3
+  data.tar.gz: 3eba30b0a03bdb9f9da1d1e4eeb6b11ec3224c0f3d02f27cc07ac1e5e7d7a41e
 SHA512:
-  metadata.gz: 689e40bffc89b7bc39c1358ef9ab69b5bd49f5840790ebd8e3ebbcfe09d4edbefcd3813e7d4ab8165783a6613624cb1625921140ecb45c124dafc6b5dc424425
-  data.tar.gz: 658be41e0d4d602f3a6167f5c380268eff5000114dd117d0edbe0ba8ddda25061935119f07d2f21e286892f46f33b779c785d9104de5a3f4cea10d661a42e093
+  metadata.gz: 9ea8d371279ec9bf8feeaa85895f25733247c8ecb059d599f34e8ecc85b4b124c05dee5421414d28c24316d7c4e69bdff622c31b182e9f883456836a6aab17ed
+  data.tar.gz: 55ddefa4f011c2dccf235043cad5ad334418c394ced59a960b993d18ead0850f7d60875a3edbdc55418d3a9d3045cef1d607170fea0ae484f4dc62bc13f15ca2

data/lib/async/clock.rb

@@ -36,6 +36,9 @@ module Async
 			@started = nil
 		end
 		
+		# @returns [Numeric | Nil] The time when the clock was started, or nil if not started.
+		attr :started
+		
 		# Start measuring a duration.
 		def start!
 			@started ||= Clock.now
@@ -70,5 +73,22 @@ module Async
 				@started = Clock.now
 			end
 		end
+		
+		# Convert the clock to a JSON-compatible hash.
+		#
+		# @returns [Hash] The JSON-compatible hash.
+		def as_json(...)
+			{
+				started: self.started,
+				total: self.total,
+			}
+		end
+		
+		# Convert the clock to a JSON string.
+		#
+		# @returns [String] The JSON string.
+		def to_json(...)
+			self.as_json.to_json(...)
+		end
 	end
 end

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.2"
+	VERSION = "2.36.0"
 end

data/readme.md

@@ -35,6 +35,15 @@ 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.
+
 ### v2.35.2
 
   - Improved handling of `Process.fork` on Ruby 4+.
@@ -68,23 +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.
-
-### v2.29.0
-
-This release introduces thread-safety as a core concept of Async. Many core classes now have thread-safe guarantees, allowing them to be used safely across multiple threads.
-
-  - Thread-safe `Async::Condition` and `Async::Notification`, implemented using `Thread::Queue`.
-  - Thread-safe `Async::Queue` and `Async::LimitedQueue`, implemented using `Thread::Queue` and `Thread::LimitedQueue` respectively.
-  - `Async::Variable` is deprecated in favor of `Async::Promise`.
-  - [Introduce `Async::Promise`](https://socketry.github.io/async/releases/index#introduce-async::promise)
-  - [Introduce `Async::PriorityQueue`](https://socketry.github.io/async/releases/index#introduce-async::priorityqueue)
-
 ## See Also
 
   - [async-http](https://github.com/socketry/async-http) — Asynchronous HTTP client/server.

data/releases.md

@@ -1,5 +1,14 @@
 # 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.
+
 ## v2.35.2
 
   - Improved handling of `Process.fork` on Ruby 4+.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async
 version: !ruby/object:Gem::Version
-  version: 2.35.2
+  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
-```