authorgravatar for mathieu.guaypaquet@gmail.comMathieu Guay-Paquet <mathieu.guaypaquet@gmail.com> 2021-04-02 14:57:42-04:00
committergravatar for noreply@github.comGitHub <noreply@github.com> 2021-04-02 14:57:42-04:00
logf270bef9a4d21e880826cef6b5264acdc84f0a6f
tree4de4fbc10e8846ab6690dd94143a31bc702ea234
parent354c14d6a28038bea4cbe30d19cadb491b6da94b
signature Signed by PGP key 4AEE18F83AFDEB23

docs: document the nosuspend keyword (#7972)

* 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".

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

doc/langref.html.in+14-9
......@@ -6594,13 +6594,11 @@ const std = @import("std");
65946594const expect = std.testing.expect;
65956595
65966596test "async and await" {
6597 // Here we have an exception where we do not match an async
6598 // with an await. The test block is not async and so cannot
6599 // have a suspend point in it.
6600 // This is well-defined behavior, and everything is OK here.
6601 // Note however that there would be no way to collect the
6602 // return value of amain, if it were something other than void.
6603 _ = async amain();
6597 // The test block is not async and so cannot have a suspend
6598 // point in it. By using the nosuspend keyword, we promise that
6599 // the code in amain will finish executing without suspending
6600 // back to the test block.
6601 nosuspend amain();
66046602}
66056603
66066604fn amain() void {
......@@ -10799,9 +10797,16 @@ fn readU32Be() u32 {}
1079910797 <pre>{#syntax#}nosuspend{#endsyntax#}</pre>
1080010798 </td>
1080110799 <td>
10802 The {#syntax#}nosuspend{#endsyntax#} keyword.
10800 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.
10801 In particular, inside a {#syntax#}nosuspend{#endsyntax#} scope:
10802 <ul>
10803 <li>Using the {#syntax#}suspend{#endsyntax#} keyword results in a compile error.</li>
10804 <li>Using {#syntax#}await{#endsyntax#} on a function frame which hasn't completed yet results in safety-checked {#link|Undefined Behavior#}.</li>
10805 <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>
10806 </ul>
10807 Code inside a {#syntax#}nosuspend{#endsyntax#} scope does not cause the enclosing function to become an {#link|async function|Async Functions#}.
1080310808 <ul>
10804 <li>TODO add documentation for nosuspend</li>
10809 <li>See also {#link|Async Functions#}</li>
1080510810 </ul>
1080610811 </td>
1080710812 </tr>