authorgravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2025-11-21 08:49:26-08:00
committergravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2025-11-21 19:54:41-08:00
logb4ec78906cdb2a13b08f94690fb270726bbdb819
treeb7aa7cc8716686ed4489808b7b04c1a4346e48aa
parent69f9395b382eb564285367e539d43dc6c8edd257

std.Io: update async documentation to reflect the guarantee

1 files changed, 16 insertions(+), 2 deletions(-)

lib/std/Io.zig+16-2
...@@ -580,6 +580,9 @@ pub const VTable = struct {...@@ -580,6 +580,9 @@ pub const VTable = struct {
580 /// If it returns `null` it means `result` has been already populated and580 /// If it returns `null` it means `result` has been already populated and
581 /// `await` will be a no-op.581 /// `await` will be a no-op.
582 ///582 ///
583 /// When this function returns non-null, the implementation guarantees that
584 /// a unit of concurrency has been assigned to the returned task.
585 ///
583 /// Thread-safe.586 /// Thread-safe.
584 async: *const fn (587 async: *const fn (
585 /// Corresponds to `Io.userdata`.588 /// Corresponds to `Io.userdata`.
...@@ -1024,6 +1027,10 @@ pub const Group = struct {...@@ -1024,6 +1027,10 @@ pub const Group = struct {
1024 ///1027 ///
1025 /// `function` *may* be called immediately, before `async` returns.1028 /// `function` *may* be called immediately, before `async` returns.
1026 ///1029 ///
1030 /// When this function returns, it is guaranteed that `function` has
1031 /// already been called and completed, or it has successfully been assigned
1032 /// a unit of concurrency.
1033 ///
1027 /// After this is called, `wait` or `cancel` must be called before the1034 /// After this is called, `wait` or `cancel` must be called before the
1028 /// group is deinitialized.1035 /// group is deinitialized.
1029 ///1036 ///
...@@ -1094,6 +1101,10 @@ pub fn Select(comptime U: type) type {...@@ -1094,6 +1101,10 @@ pub fn Select(comptime U: type) type {
1094 ///1101 ///
1095 /// `function` *may* be called immediately, before `async` returns.1102 /// `function` *may* be called immediately, before `async` returns.
1096 ///1103 ///
1104 /// When this function returns, it is guaranteed that `function` has
1105 /// already been called and completed, or it has successfully been
1106 /// assigned a unit of concurrency.
1107 ///
1097 /// After this is called, `wait` or `cancel` must be called before the1108 /// After this is called, `wait` or `cancel` must be called before the
1098 /// select is deinitialized.1109 /// select is deinitialized.
1099 ///1110 ///
...@@ -1524,8 +1535,11 @@ pub fn Queue(Elem: type) type {...@@ -1524,8 +1535,11 @@ pub fn Queue(Elem: type) type {
1524/// not guaranteed to be available until `await` is called.1535/// not guaranteed to be available until `await` is called.
1525///1536///
1526/// `function` *may* be called immediately, before `async` returns. This has1537/// `function` *may* be called immediately, before `async` returns. This has
1527/// weaker guarantees than `concurrent`, making more portable and1538/// weaker guarantees than `concurrent`, making more portable and reusable.
1528/// reusable.1539///
1540/// When this function returns, it is guaranteed that `function` has already
1541/// been called and completed, or it has successfully been assigned a unit of
1542/// concurrency.
1529///1543///
1530/// See also:1544/// See also:
1531/// * `Group`1545/// * `Group`