From 56265d6f9934f7321d2001c9d07ce82b0c9be126 Mon Sep 17 00:00:00 2001
From: Andrew Kelley <andrew@ziglang.org>
Date: Tue, 5 May 2026 13:38:32 -0700
Subject: [PATCH] std.Io: clarify Group semantics with respect to async tasks

---
 lib/std/Io.zig | 20 +++++++++++---------
 1 file changed, 11 insertions(+), 9 deletions(-)

diff --git a/lib/std/Io.zig b/lib/std/Io.zig
index 4816844482ec4649238d3fdcef835636a80aceb5..f3ef2757acad16f3dc4e548cc25d1172ba47e032 100644
--- a/lib/std/Io.zig
+++ b/lib/std/Io.zig
@@ -54,9 +54,6 @@ pub const VTable = struct {
     /// If it returns `null` it means `result` has been already populated and
     /// `await` will be a no-op.
     ///
-    /// When this function returns non-null, the implementation guarantees that
-    /// a unit of concurrency has been assigned to the returned task.
-    ///
     /// Thread-safe.
     async: *const fn (
         /// Corresponds to `Io.userdata`.
@@ -111,10 +108,6 @@ pub const VTable = struct {
         result_alignment: std.mem.Alignment,
     ) void,
 
-    /// When this function returns, implementation guarantees that `start` has
-    /// either already been called, or a unit of concurrency has been assigned
-    /// to the task of calling the function.
-    ///
     /// Thread-safe.
     groupAsync: *const fn (
         /// Corresponds to `Io.userdata`.
@@ -1251,8 +1244,11 @@ pub const Group = struct {
     /// cancelation propagation boundary.
     ///
     /// Once this function is called, there are resources associated with the
-    /// group. To release those resources, `Group.await` or `Group.cancel` must
-    /// eventually be called.
+    /// group. To release those resources, `await` or `cancel` must eventually
+    /// be called.
+    ///
+    /// `function` is not guaranteed to have been called until `await` or
+    /// `cancel` is called.
     pub fn async(g: *Group, io: Io, function: anytype, args: std.meta.ArgsTuple(@TypeOf(function))) void {
         const Args = @TypeOf(args);
         const TypeErased = struct {
@@ -1290,6 +1286,9 @@ pub const Group = struct {
     /// will also cause `error.Canceled` to be returned when the group
     /// does ultimately finish.
     ///
+    /// After this function returns, all tasks of the `Group` created with
+    /// `async` or `concurrent` are guaranteed to have run.
+    ///
     /// Idempotent. Not threadsafe.
     ///
     /// It is safe to call this function concurrently with `Group.async` or
@@ -1304,6 +1303,9 @@ pub const Group = struct {
     /// Equivalent to `await` but immediately requests cancelation on all
     /// members of the group.
     ///
+    /// After this function returns, all tasks of the `Group` created with
+    /// `async` or `concurrent` are guaranteed to have run.
+    ///
     /// For a description of cancelation and cancelation points, see `Future.cancel`.
     ///
     /// Idempotent. Not threadsafe.
-- 
2.54.0