authorgravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2026-05-05 13:38:32-07:00
committergravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2026-05-05 13:39:24-07:00
log56265d6f9934f7321d2001c9d07ce82b0c9be126
tree9b91764a4bda077af862a1152cadf1f16d5c46d8
parent3fafbd2e35b05c98971b8d81514d2f92670c7b89

std.Io: clarify Group semantics with respect to async tasks

1 files changed, 11 insertions(+), 9 deletions(-)

lib/std/Io.zig+11-9
...@@ -54,9 +54,6 @@ pub const VTable = struct {...@@ -54,9 +54,6 @@ pub const VTable = struct {
54 /// If it returns `null` it means `result` has been already populated and54 /// If it returns `null` it means `result` has been already populated and
55 /// `await` will be a no-op.55 /// `await` will be a no-op.
56 ///56 ///
57 /// When this function returns non-null, the implementation guarantees that
58 /// a unit of concurrency has been assigned to the returned task.
59 ///
60 /// Thread-safe.57 /// Thread-safe.
61 async: *const fn (58 async: *const fn (
62 /// Corresponds to `Io.userdata`.59 /// Corresponds to `Io.userdata`.
...@@ -111,10 +108,6 @@ pub const VTable = struct {...@@ -111,10 +108,6 @@ pub const VTable = struct {
111 result_alignment: std.mem.Alignment,108 result_alignment: std.mem.Alignment,
112 ) void,109 ) void,
113110
114 /// When this function returns, implementation guarantees that `start` has
115 /// either already been called, or a unit of concurrency has been assigned
116 /// to the task of calling the function.
117 ///
118 /// Thread-safe.111 /// Thread-safe.
119 groupAsync: *const fn (112 groupAsync: *const fn (
120 /// Corresponds to `Io.userdata`.113 /// Corresponds to `Io.userdata`.
...@@ -1251,8 +1244,11 @@ pub const Group = struct {...@@ -1251,8 +1244,11 @@ pub const Group = struct {
1251 /// cancelation propagation boundary.1244 /// cancelation propagation boundary.
1252 ///1245 ///
1253 /// Once this function is called, there are resources associated with the1246 /// Once this function is called, there are resources associated with the
1254 /// group. To release those resources, `Group.await` or `Group.cancel` must1247 /// group. To release those resources, `await` or `cancel` must eventually
1255 /// eventually be called.1248 /// be called.
1249 ///
1250 /// `function` is not guaranteed to have been called until `await` or
1251 /// `cancel` is called.
1256 pub fn async(g: *Group, io: Io, function: anytype, args: std.meta.ArgsTuple(@TypeOf(function))) void {1252 pub fn async(g: *Group, io: Io, function: anytype, args: std.meta.ArgsTuple(@TypeOf(function))) void {
1257 const Args = @TypeOf(args);1253 const Args = @TypeOf(args);
1258 const TypeErased = struct {1254 const TypeErased = struct {
...@@ -1290,6 +1286,9 @@ pub const Group = struct {...@@ -1290,6 +1286,9 @@ pub const Group = struct {
1290 /// will also cause `error.Canceled` to be returned when the group1286 /// will also cause `error.Canceled` to be returned when the group
1291 /// does ultimately finish.1287 /// does ultimately finish.
1292 ///1288 ///
1289 /// After this function returns, all tasks of the `Group` created with
1290 /// `async` or `concurrent` are guaranteed to have run.
1291 ///
1293 /// Idempotent. Not threadsafe.1292 /// Idempotent. Not threadsafe.
1294 ///1293 ///
1295 /// It is safe to call this function concurrently with `Group.async` or1294 /// It is safe to call this function concurrently with `Group.async` or
...@@ -1304,6 +1303,9 @@ pub const Group = struct {...@@ -1304,6 +1303,9 @@ pub const Group = struct {
1304 /// Equivalent to `await` but immediately requests cancelation on all1303 /// Equivalent to `await` but immediately requests cancelation on all
1305 /// members of the group.1304 /// members of the group.
1306 ///1305 ///
1306 /// After this function returns, all tasks of the `Group` created with
1307 /// `async` or `concurrent` are guaranteed to have run.
1308 ///
1307 /// For a description of cancelation and cancelation points, see `Future.cancel`.1309 /// For a description of cancelation and cancelation points, see `Future.cancel`.
1308 ///1310 ///
1309 /// Idempotent. Not threadsafe.1311 /// Idempotent. Not threadsafe.