Commit 2a02c7a0d59e25bac07a6ed2948a29438fb05527 | zig

author	Andrew Kelley <andrew@ziglang.org> 2025-12-29 18:24:40-08:00
committer	Andrew Kelley <andrew@ziglang.org> 2025-12-29 22:51:06-08:00
log	2a02c7a0d59e25bac07a6ed2948a29438fb05527
tree	e68a1855272d8d64d1934802501eb2d45f0992f3
parent	2adfd4d107f071f91608bef22c7e91b1a9a93470

std.Io.Group: async and concurrent support Cancelable results

Now, the return type of functions spawned with `Group.async` and
`Group.concurrent` may be anything that coerces to `Io.Cancelable!void`.

Before this commit, group tasks were the only exception to the rule
"error.Canceled should never be swallowed". Now, there is no exception,
and it is enforced with an assertion upon closure completion.

Finally, fixes a case of swallowing error.Canceled in the compiler,
solving a TODO.

There are three ways to handle `error.Canceled`. In order of most
common:
1. Propagate it
2. After receiving it, io.recancel() and then don't propagate it
3. Make it unreachable with io.swapCancelProtection()

4 files changed, 61 insertions(+), 24 deletions(-)

lib
- std
  - Io.zig
  - Io
    Threaded.zig
    test.zig
src
- Package
  - Fetch.zig

lib/std/Io.zig+7-7

lib/std/Io/Threaded.zig+25-9

 @@ -1279,7 +1279,7 @@ const GroupClosure = struct {
     group: *Io.Group,
     /// Points to sibling `GroupClosure`. Used for walking the group to cancel all.
     node: std.SinglyLinkedList.Node,
-    func: *const fn (*Io.Group, context: *anyopaque) void,
+    func: *const fn (*Io.Group, context: *anyopaque) Io.Cancelable!void,
     context_alignment: Alignment,
     alloc_len: usize,
 @@ -1292,7 +1292,7 @@ const GroupClosure = struct {
         current_thread.current_closure = closure;
         current_thread.cancel_protection = .unblocked;
-        gc.func(group, gc.contextPointer());
+        assertResult(closure, gc.func(group, gc.contextPointer()));
         current_thread.current_closure = null;
         current_thread.cancel_protection = undefined;
 @@ -1302,6 +1302,16 @@ const GroupClosure = struct {
         if (prev_state == (sync_one_pending | sync_is_waiting)) event.set(ioBasic(t));
     }
+    fn assertResult(closure: *Closure, result: Io.Cancelable!void) void {
+        if (result) |_| switch (closure.cancel_status.unpack()) {
+            .none, .requested => {},
+            .acknowledged => unreachable, // task illegally swallowed error.Canceled
+            .signal_id => unreachable,
+        } else |err| switch (err) {
+            error.Canceled => assert(closure.cancel_status == .acknowledged),
+        }
+    }
     fn contextPointer(gc: *GroupClosure) [*]u8 {
         const base: [*]u8 = @ptrCast(gc);
         const context_offset = gc.context_alignment.forward(@intFromPtr(gc) + @sizeOf(GroupClosure)) - @intFromPtr(gc);
 @@ -1314,7 +1324,7 @@ const GroupClosure = struct {
         group: *Io.Group,
         context: []const u8,
         context_alignment: Alignment,
-        func: *const fn (*Io.Group, context: *const anyopaque) void,
+        func: *const fn (*Io.Group, context: *const anyopaque) Io.Cancelable!void,
     ) Allocator.Error!*GroupClosure {
         const max_context_misalignment = context_alignment.toByteUnits() -| @alignOf(GroupClosure);
         const worst_case_context_offset = context_alignment.forward(@sizeOf(GroupClosure) + max_context_misalignment);
 @@ -1352,14 +1362,14 @@ fn groupAsync(
     group: *Io.Group,
     context: []const u8,
     context_alignment: Alignment,
-    start: *const fn (*Io.Group, context: *const anyopaque) void,
+    start: *const fn (*Io.Group, context: *const anyopaque) Io.Cancelable!void,
 ) void {
     const t: *Threaded = @ptrCast(@alignCast(userdata));
-    if (builtin.single_threaded) return start(group, context.ptr);
+    if (builtin.single_threaded) return start(group, context.ptr) catch unreachable;
     const gpa = t.allocator;
     const gc = GroupClosure.init(gpa, group, context, context_alignment, start) catch
-        return start(group, context.ptr);
+        return t.assertGroupResult(start(group, context.ptr));
     t.mutex.lock();
 @@ -1368,7 +1378,7 @@ fn groupAsync(
     if (busy_count >= @intFromEnum(t.async_limit)) {
         t.mutex.unlock();
         gc.deinit(gpa);
-        return start(group, context.ptr);
+        return t.assertGroupResult(start(group, context.ptr));
     }
     t.busy_count = busy_count + 1;
 @@ -1381,7 +1391,7 @@ fn groupAsync(
             t.busy_count = busy_count;
             t.mutex.unlock();
             gc.deinit(gpa);
-            return start(group, context.ptr);
+            return t.assertGroupResult(start(group, context.ptr));
         };
         thread.detach();
     }
 @@ -1402,12 +1412,18 @@ fn groupAsync(
     t.cond.signal();
 }
+fn assertGroupResult(t: *Threaded, result: Io.Cancelable!void) void {
+    const current_thread: *Thread = .getCurrent(t);
+    const current_closure = current_thread.current_closure orelse return;
+    GroupClosure.assertResult(current_closure, result);
+}
 fn groupConcurrent(
     userdata: ?*anyopaque,
     group: *Io.Group,
     context: []const u8,
     context_alignment: Alignment,
-    start: *const fn (*Io.Group, context: *const anyopaque) void,
+    start: *const fn (*Io.Group, context: *const anyopaque) Io.Cancelable!void,
 ) Io.ConcurrentError!void {
     if (builtin.single_threaded) return error.ConcurrencyUnavailable;

lib/std/Io/test.zig+27-6

 @@ -207,27 +207,48 @@ fn count(a: usize, b: usize, result: *usize) void {
     result.* = sum;
 }
-test "Group cancellation" {
+test "Group cancelation" {
     const io = testing.io;
     var group: Io.Group = .init;
-    var results: [2]usize = undefined;
+    var results: [4]usize = .{ 0, 0, 0, 0 };
+    // TODO when robust cancelation is available, make the sleep timeouts much
+    // longer so that it causes the unit test to be failed if not canceled.
+    // https://codeberg.org/ziglang/zig/issues/30049
     group.async(io, sleep, .{ io, &results[0] });
     group.async(io, sleep, .{ io, &results[1] });
+    group.async(io, sleepUncancelable, .{ io, &results[2] });
+    group.async(io, sleepRecancel, .{ io, &results[3] });
     group.cancel(io);
-    try testing.expectEqualSlices(usize, &.{ 1, 1 }, &results);
+    try testing.expectEqualSlices(usize, &.{ 1, 1, 1, 1 }, &results);
+}
+fn sleep(io: Io, result: *usize) error{Canceled}!void {
+    defer result.* = 1;
+    io.sleep(.fromMilliseconds(1), .awake) catch |err| switch (err) {
+        error.Canceled => |e| return e,
+        else => {},
+    };
 }
-fn sleep(io: Io, result: *usize) void {
+fn sleepUncancelable(io: Io, result: *usize) void {
-    // TODO when cancellation race bug is fixed, make this timeout much longer so that
+    const old_prot = io.swapCancelProtection(.blocked);
-    // it causes the unit test to be failed if not canceled.
+    defer _ = io.swapCancelProtection(old_prot);
     io.sleep(.fromMilliseconds(1), .awake) catch {};
     result.* = 1;
 }
+fn sleepRecancel(io: Io, result: *usize) void {
+    io.sleep(.fromMilliseconds(1), .awake) catch |err| switch (err) {
+        error.Canceled => io.recancel(),
+        else => {},
+    };
+    result.* = 1;
+}
 test "Group concurrent" {
     const io = testing.io;

src/Package/Fetch.zig+2-2

...	@@ -843,13 +843,13 @@ pub fn relativePathDigest(pkg_root: Cache.Path, cache_root: Cache.Directory) Pac	...	@@ -843,13 +843,13 @@ pub fn relativePathDigest(pkg_root: Cache.Path, cache_root: Cache.Directory) Pac
843	return .initPath(pkg_root.sub_path, pkg_root.root_dir.eql(cache_root));	843	return .initPath(pkg_root.sub_path, pkg_root.root_dir.eql(cache_root));
844	}	844	}
845		845
846	pub fn workerRun(f: *Fetch, prog_name: []const u8) void {	846	pub fn workerRun(f: *Fetch, prog_name: []const u8) Io.Cancelable!void {
847	const prog_node = f.prog_node.start(prog_name, 0);	847	const prog_node = f.prog_node.start(prog_name, 0);
848	defer prog_node.end();	848	defer prog_node.end();
849		849
850	run(f) catch \|err\| switch (err) {	850	run(f) catch \|err\| switch (err) {
851	error.OutOfMemory => f.oom_flag = true,	851	error.OutOfMemory => f.oom_flag = true,
852	error.Canceled => {}, // TODO make groupAsync functions be cancelable and assert proper value was returned	852	error.Canceled => \|e\| return e,
853	error.FetchFailed => {	853	error.FetchFailed => {
854	// Nothing to do because the errors are already reported in `error_bundle`,	854	// Nothing to do because the errors are already reported in `error_bundle`,
855	// and a reference is kept to the `Fetch` task inside `all_fetches`.	855	// and a reference is kept to the `Fetch` task inside `all_fetches`.

...	@@ -631,7 +631,7 @@ pub const VTable = struct {	...	@@ -631,7 +631,7 @@ pub const VTable = struct {
631	/// Copied and then passed to `start`.	631	/// Copied and then passed to `start`.
632	context: []const u8,	632	context: []const u8,
633	context_alignment: std.mem.Alignment,	633	context_alignment: std.mem.Alignment,
634	start: const fn (Group, context: *const anyopaque) void,	634	start: const fn (Group, context: *const anyopaque) Cancelable!void,
635	) void,	635	) void,
636	/// Thread-safe.	636	/// Thread-safe.
637	groupConcurrent: *const fn (	637	groupConcurrent: *const fn (
...	@@ -642,7 +642,7 @@ pub const VTable = struct {	...	@@ -642,7 +642,7 @@ pub const VTable = struct {
642	/// Copied and then passed to `start`.	642	/// Copied and then passed to `start`.
643	context: []const u8,	643	context: []const u8,
644	context_alignment: std.mem.Alignment,	644	context_alignment: std.mem.Alignment,
645	start: const fn (Group, context: *const anyopaque) void,	645	start: const fn (Group, context: *const anyopaque) Cancelable!void,
646	) ConcurrentError!void,	646	) ConcurrentError!void,
647	groupAwait: const fn (?anyopaque, Group, token: anyopaque) Cancelable!void,	647	groupAwait: const fn (?anyopaque, Group, token: anyopaque) Cancelable!void,
648	groupCancel: const fn (?anyopaque, Group, token: anyopaque) void,	648	groupCancel: const fn (?anyopaque, Group, token: anyopaque) void,
...	@@ -1082,10 +1082,10 @@ pub const Group = struct {	...	@@ -1082,10 +1082,10 @@ pub const Group = struct {
1082	pub fn async(g: *Group, io: Io, function: anytype, args: std.meta.ArgsTuple(@TypeOf(function))) void {	1082	pub fn async(g: *Group, io: Io, function: anytype, args: std.meta.ArgsTuple(@TypeOf(function))) void {
1083	const Args = @TypeOf(args);	1083	const Args = @TypeOf(args);
1084	const TypeErased = struct {	1084	const TypeErased = struct {
1085	fn start(group: Group, context: const anyopaque) void {	1085	fn start(group: Group, context: const anyopaque) Cancelable!void {
1086	_ = group;	1086	_ = group;
1087	const args_casted: *const Args = @ptrCast(@alignCast(context));	1087	const args_casted: *const Args = @ptrCast(@alignCast(context));
1088	@call(.auto, function, args_casted.*);	1088	return @call(.auto, function, args_casted.*);
1089	}	1089	}
1090	};	1090	};
1091	io.vtable.groupAsync(io.userdata, g, @ptrCast(&args), .of(Args), TypeErased.start);	1091	io.vtable.groupAsync(io.userdata, g, @ptrCast(&args), .of(Args), TypeErased.start);
...	@@ -1110,10 +1110,10 @@ pub const Group = struct {	...	@@ -1110,10 +1110,10 @@ pub const Group = struct {
1110	pub fn concurrent(g: *Group, io: Io, function: anytype, args: std.meta.ArgsTuple(@TypeOf(function))) ConcurrentError!void {	1110	pub fn concurrent(g: *Group, io: Io, function: anytype, args: std.meta.ArgsTuple(@TypeOf(function))) ConcurrentError!void {
1111	const Args = @TypeOf(args);	1111	const Args = @TypeOf(args);
1112	const TypeErased = struct {	1112	const TypeErased = struct {
1113	fn start(group: Group, context: const anyopaque) void {	1113	fn start(group: Group, context: const anyopaque) Cancelable!void {
1114	_ = group;	1114	_ = group;
1115	const args_casted: *const Args = @ptrCast(@alignCast(context));	1115	const args_casted: *const Args = @ptrCast(@alignCast(context));
1116	@call(.auto, function, args_casted.*);	1116	return @call(.auto, function, args_casted.*);
1117	}	1117	}
1118	};	1118	};
1119	return io.vtable.groupConcurrent(io.userdata, g, @ptrCast(&args), .of(Args), TypeErased.start);	1119	return io.vtable.groupConcurrent(io.userdata, g, @ptrCast(&args), .of(Args), TypeErased.start);
...	@@ -1265,7 +1265,7 @@ pub fn Select(comptime U: type) type {	...	@@ -1265,7 +1265,7 @@ pub fn Select(comptime U: type) type {
1265	) void {	1265	) void {
1266	const Args = @TypeOf(args);	1266	const Args = @TypeOf(args);
1267	const TypeErased = struct {	1267	const TypeErased = struct {
1268	fn start(group: Group, context: const anyopaque) void {	1268	fn start(group: Group, context: const anyopaque) Cancelable!void {
1269	const args_casted: *const Args = @ptrCast(@alignCast(context));	1269	const args_casted: *const Args = @ptrCast(@alignCast(context));
1270	const unerased_select: *S = @fieldParentPtr("group", group);	1270	const unerased_select: *S = @fieldParentPtr("group", group);
1271	const elem = @unionInit(U, @tagName(field), @call(.auto, function, args_casted.*));	1271	const elem = @unionInit(U, @tagName(field), @call(.auto, function, args_casted.*));