Nixyri/zig
1
0
Fork 0
mirror of https://github.com/ziglang/zig.git synced 2024-11-14 16:13:24 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: document the nosuspend keyword (#7972)

Browse Source 
* docs: document the nosuspend keyword

* Specify that resuming from suspend is allowed in nosuspend

* Fix the description of the requirements of nosuspend

* Make use of nosuspend in some example code.

This is mainly motivated by the incorrect claim that "there would be
no way to collect the return value of amain, if it were something
other than void".
This commit is contained in:
Mathieu Guay-Paquet 2021-04-02 14:57:42 -04:00 committed by GitHub
parent 354c14d6a2
commit f270bef9a4
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 14 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
doc/langref.html.in
View File

@ -6594,13 +6594,11 @@ const std = @import("std");
const expect = std.testing.expect;
test "async and await" {
// Here we have an exception where we do not match an async
// with an await. The test block is not async and so cannot
// have a suspend point in it.
// This is well-defined behavior, and everything is OK here.
// Note however that there would be no way to collect the
// return value of amain, if it were something other than void.
_ = async amain();
// The test block is not async and so cannot have a suspend
// point in it. By using the nosuspend keyword, we promise that
// the code in amain will finish executing without suspending
// back to the test block.
nosuspend amain();
}
fn amain() void {
@ -10799,9 +10797,16 @@ fn readU32Be() u32 {}
<pre>{#syntax#}nosuspend{#endsyntax#}</pre>
</td>
<td>
The {#syntax#}nosuspend{#endsyntax#} keyword.
The {#syntax#}nosuspend{#endsyntax#} keyword can be used in front of a block, statement or expression, to mark a scope where no suspension points are reached.
In particular, inside a {#syntax#}nosuspend{#endsyntax#} scope:
<ul>
<li>TODO add documentation for nosuspend</li>
<li>Using the {#syntax#}suspend{#endsyntax#} keyword results in a compile error.</li>
<li>Using {#syntax#}await{#endsyntax#} on a function frame which hasn't completed yet results in safety-checked {#link|Undefined Behavior#}.</li>
<li>Calling an async function may result in safety-checked {#link|Undefined Behavior#}, because it's equivalent to <code>await async some_async_fn()</code>, which contains an {#syntax#}await{#endsyntax#}.</li>
</ul>
Code inside a {#syntax#}nosuspend{#endsyntax#} scope does not cause the enclosing function to become an {#link|async function|Async Functions#}.
<ul>
<li>See also {#link|Async Functions#}</li>
</ul>
</td>
</tr>