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");...@@ -6594,13 +6594,11 @@ const std = @import("std");
6594const expect = std.testing.expect;6594const expect = std.testing.expect;
65956595
6596test "async and await" {6596test "async and await" {
6597 // Here we have an exception where we do not match an async6597 // The test block is not async and so cannot have a suspend
6598 // with an await. The test block is not async and so cannot6598 // point in it. By using the nosuspend keyword, we promise that
6599 // have a suspend point in it.6599 // the code in amain will finish executing without suspending
6600 // This is well-defined behavior, and everything is OK here.6600 // back to the test block.
6601 // Note however that there would be no way to collect the6601 nosuspend amain();
6602 // return value of amain, if it were something other than void.
6603 _ = async amain();
6604}6602}
66056603
6606fn amain() void {6604fn amain() void {
...@@ -10799,9 +10797,16 @@ fn readU32Be() u32 {}...@@ -10799,9 +10797,16 @@ fn readU32Be() u32 {}
10799 <pre>{#syntax#}nosuspend{#endsyntax#}</pre>10797 <pre>{#syntax#}nosuspend{#endsyntax#}</pre>
10800 </td>10798 </td>
10801 <td>10799 <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#}.
10803 <ul>10808 <ul>
10804 <li>TODO add documentation for nosuspend</li>10809 <li>See also {#link|Async Functions#}</li>
10805 </ul>10810 </ul>
10806 </td>10811 </td>
10807 </tr>10812 </tr>