authorgravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2026-01-30 11:45:08-08:00
committergravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2026-01-30 20:21:07-08:00
log13f13fe0a7e1dcc1a224efff0de89cdd36f11ca6
tree8244e7747ab6b62155739daed5d2fc9c9fc4f336
parent9f6152ae93037b7e69c14dba5691b146f670b3f8

std.Io: add documentation to Batch

2 files changed, 31 insertions(+), 5 deletions(-)

lib/std/Io.zig+30-4
......@@ -150,7 +150,7 @@ pub const VTable = struct {
150150 futexWake: *const fn (?*anyopaque, ptr: *const u32, max_waiters: u32) void,
151151
152152 operate: *const fn (?*anyopaque, Operation) Cancelable!Operation.Result,
153 batchAwaitAsync: *const fn (?*anyopaque, *Batch) Batch.AwaitAsyncError!void,
153 batchAwaitAsync: *const fn (?*anyopaque, *Batch) Cancelable!void,
154154 batchAwaitConcurrent: *const fn (?*anyopaque, *Batch, Timeout) Batch.AwaitConcurrentError!void,
155155 batchCancel: *const fn (?*anyopaque, *Batch) void,
156156
......@@ -359,7 +359,7 @@ pub fn operate(io: Io, operation: Operation) Cancelable!Operation.Result {
359359/// complete.
360360///
361361/// This is a low-level abstraction based on `Operation`. For a higher
362/// level API that operates on `Future`, see `Select`.
362/// level API that operates on `Future`, see `Select` and `Group`.
363363pub const Batch = struct {
364364 storage: []Operation.Storage,
365365 unused: Operation.List,
......@@ -422,6 +422,11 @@ pub const Batch = struct {
422422 b.submissions.tail = .fromIndex(index);
423423 }
424424
425 /// After calling `awaitAsync`, `awaitConcurrent`, or `cancel`, this
426 /// function iterates over the completed operations.
427 ///
428 /// Each completion returned from this function dequeues from the `Batch`.
429 /// It is not required to dequeue all completions before awaiting again.
425430 pub fn next(b: *Batch) ?struct { index: u32, result: Operation.Result } {
426431 const index = b.completions.head;
427432 if (index == .none) return null;
......@@ -441,16 +446,37 @@ pub const Batch = struct {
441446 return .{ .index = index.toIndex(), .result = completion.result };
442447 }
443448
444 pub const AwaitAsyncError = Cancelable;
445 pub fn awaitAsync(b: *Batch, io: Io) AwaitAsyncError!void {
449 /// Waits for at least one of the submitted operations to complete. After
450 /// this function returns the completed operations can be iterated with
451 /// `next`.
452 ///
453 /// This function provides opportunity for the implementation to introduce
454 /// concurrency into the batched operations, but unlike `awaitConcurrent`,
455 /// does not require it, and therefore cannot fail with
456 /// `error.ConcurrencyUnavailable`.
457 pub fn awaitAsync(b: *Batch, io: Io) Cancelable!void {
446458 return io.vtable.batchAwaitAsync(io.userdata, b);
447459 }
448460
449461 pub const AwaitConcurrentError = ConcurrentError || Cancelable || Timeout.Error;
462
463 /// Waits for at least one of the submitted operations to complete. After
464 /// this function returns the completed operations can be iterated with
465 /// `next`.
466 ///
467 /// Unlike `awaitAsync`, this function requires the implementation to
468 /// perform the operations concurrently and therefore can fail with
469 /// `error.ConcurrencyUnavailable`.
450470 pub fn awaitConcurrent(b: *Batch, io: Io, timeout: Timeout) AwaitConcurrentError!void {
451471 return io.vtable.batchAwaitConcurrent(io.userdata, b, timeout);
452472 }
453473
474 /// Requests all pending operations to be interrupted, then waits for all
475 /// pending operations to complete. After this returns, the `Batch` is in a
476 /// well-defined state, ready to be iterated with `next`. Successfully
477 /// canceled operations will be absent from the iteration. Some operations
478 /// may have successfully completed regardless of the cancel request and
479 /// will appear in the iteration.
454480 pub fn cancel(b: *Batch, io: Io) void {
455481 return io.vtable.batchCancel(io.userdata, b);
456482 }
lib/std/Io/Threaded.zig+1-1
......@@ -2495,7 +2495,7 @@ fn operate(userdata: ?*anyopaque, operation: Io.Operation) Io.Cancelable!Io.Oper
24952495 }
24962496}
24972497
2498fn batchAwaitAsync(userdata: ?*anyopaque, b: *Io.Batch) Io.Batch.AwaitAsyncError!void {
2498fn batchAwaitAsync(userdata: ?*anyopaque, b: *Io.Batch) Io.Cancelable!void {
24992499 const t: *Threaded = @ptrCast(@alignCast(userdata));
25002500 if (is_windows) {
25012501 batchAwaitWindows(b, false) catch |err| switch (err) {