Merge pull request #236 from nrc/adv-aa-1

Write the first half of the advanced async/await chapter

Author: nrc

src/07_workarounds/02_err_in_async_blocks.md

@@ -62,7 +62,6 @@
   - [TODO: Cancellation and Timeouts]()
   - [TODO: `FuturesUnordered`]()
 - [Workarounds to Know and Love](07_workarounds/01_chapter.md)
-  - [`?` in `async` Blocks](07_workarounds/02_err_in_async_blocks.md)
   - [`Send` Approximation](07_workarounds/03_send_approximation.md)
   - [Recursion](07_workarounds/04_recursion.md)
   - [`async` in Traits](07_workarounds/05_async_in_traits.md)

src/SUMMARY.md

@@ -2,26 +2,160 @@
 
 ## Unit tests
 
+How to unit test async code? The issue is that you can only await from inside an async context, and unit tests in Rust are not async. Luckily, most runtimes provide a convenience attribute for tests similar to the one for `async main`. Using Tokio, it looks like this:
+
+```rust,norun
+#[tokio::test]
+async fn test_something() {
+  // Write a test here, including all the `await`s you like.
+}
+```
+
+There are many ways to configure the test, see the [docs](https://docs.rs/tokio/latest/tokio/attr.test.html) for details.
+
+There are some more advanced topics in testing async code (e.g., testing for race conditions, deadlock, etc.), and we'll cover some of those [later]() in this guide.
+
+
 ## Blocking and cancellation
 
-- Two important concepts to be aware of early, we'll revisit in more detail as we go along
-- Cancellation
-  - How to do it
-    - drop a future
-    - cancellation token
-    - abort functions
-  - Why it matters, cancellation safety (forward ref)
-- Blocking
-  - IO and computation can block
-  - why it's bad
-  - how to deal is a forward ref to io chapter
+Blocking and cancellation are important to keep in mind when programming with async Rust. These concepts are not localised to any particular feature or function, but are ubiquitous properties of the system which you must understand to write correct code.
+
+### Blocking IO
+
+We say a thread (note we're talking about OS threads here, not async tasks) is blocked when it can't make any progress. That's usually because it is waiting for the OS to complete a task on its behalf (usually I/O). Importantly, while a thread is blocked, the OS knows not to schedule it so that other threads can make progress. This is fine in a multithreaded program because it lets other threads make progress while the blocked thread is waiting. However, in an async program, there are other tasks which should be scheduled on the same OS thread, but the OS doesn't know about those and keeps the whole thread waiting. This means that rather than the single task waiting for its I/O to complete (which is fine), many tasks have to wait (which is not fine).
+
+We'll talk soon about non-blocking/async I/O. For now, just know that non-blocking I/O is I/O which the async runtime knows about and so will only the current task will wait, the thread will not be blocked. It is very important to only use non-blocking I/O from an async task, never blocking I/O (which is the only kind provided in Rust's standard library).
+
+### Blocking computation
+
+You can also block the thread by doing computation (this is not quite the same as blocking I/O, since the OS is not involved, but the effect is similar). If you have a long-running computation (with or without blocking I/O) without yielding control to the runtime, then that task will never give the runtime's scheduler a chance to schedule other tasks. Remember that async programming uses cooperative multitasking. Here a task is not cooperating, so other tasks won't get a chance to get work done. We'll discuss ways to mitigate this later.
+
+There are many other ways to block a whole thread, and we'll come back to blocking several times in this guide.
+
+### Cancellation
+
+Cancellation means stopping a future (or task) from executing. Since in Rust (and in contrast to many other async/await systems), futures must be driven forward by an external force (like the async runtime), if a future is no longer driven forward then it will not execute any more. If a future is dropped (remember, a future is just a plain old Rust object), then it can never make any more progress and is canceled.
+
+Cancellation can be initiated in a few ways:
+
+- By simply dropping a future (if you own it).
+- Calling [`abort`](https://docs.rs/tokio/latest/tokio/task/struct.JoinHandle.html#method.abort) on a task's 'JoinHandle' (or an `AbortHandle`).
+- Via a [`CancellationToken`](https://docs.rs/tokio-util/latest/tokio_util/sync/struct.CancellationToken.html) (which requires the future being canceled to notice the token and cooperatively cancel itself).
+- Implicitly, by a function or macro like [`select`](https://docs.rs/tokio/latest/tokio/macro.select.html).
+
+The middle two are specific to Tokio, though most runtimes provide similar facilities. Using a `CancellationToken` requires cooperation of the future being canceled, but the others do not. In these other cases, the canceled future will get no notification of cancellation and no opportunity to clean up (besides its destructor). Note that even if a future has a cancellation token, it can still be canceled via the other methods which won't trigger the cancellation token.
+
+From the perspective of writing async code (in async functions, blocks, futures, etc.), the code might stop executing at any `await` (including hidden ones in macros) and never start again. In order for your code to be correct (specifically to be *cancellation safe*), it must work correctly whether it completes normally or whether it terminates at any await point[^cfThreads].
+
+```rust,norun
+async fn some_function(input: Option<Input>) {
+    let Some(input) = input else {
+        return;           // Might terminate here (`return`).
+    };
+
+    let x = foo(input)?;  // Might terminate here (`?`).
+
+    let y = bar(x).await; // Might terminate here (`await`).
+
+    // ...
+
+    //                       Might terminate here (implicit return).
+}
+```
+
+An example of how this can go wrong is if an async function reads data into an internal buffer, then awaits the next datum. If reading the data is destructive (i.e., cannot be re-read from the original source) and the async function is canceled, then the internal buffer will be dropped, and the data in it will be lost. It is important to consider how a future and any data it touches will be impacted by canceling the future, restarting the future, or starting a new future which touches the same data.
+
+We'll be coming back to cancellation and cancellation safety a few times in this guide, and there is a whole [chapter]() on the topic in the reference section.
+
+[^cfThreads]: It is interesting to compare cancellation in async programming with canceling threads. Canceling a thread is possible (e.g., using `pthread_cancel` in C, there is no direct way to do this in Rust), but it is almost always a very, very bad idea since the thread being canceled can terminate anywhere. in contrast, canceling an async task can only happen at an await point. As a consequence, it is very rare to cancel an OS thread without terminating the whole porcess and so as a programmer, you generally don't worry about this happening. In async Rust however, cancellation is definitely something which *can* happen. We'll be discussing how to deal with that as we go along.
+
+## Async blocks
+
+A regular block (`{ ... }`) groups code together in the source and creates a scope of encapsulation for names. At runtime, the block is executed in order and evaluates to the value of its last expression (or the unit type (`()`) if there is no trailing expression).
+
+Similarly to async functions, an async block is a deferred version of a regular block. An async block scopes code and names together, but at runtime it is not immediately executed and evaluates to a future. To execute the block and obtain the result, it must be `await`ed. E.g.:
+
+```rust,norun
+let s1 = {
+    let a = 42;
+    format!("The answer is {a}")
+};
+
+let s2 = async {
+    let q = question().await;
+    format!("The question is {q}")
+};
+```
+
+If we were to execute this snippet, `s1` would be a string which could be printed, but `s2` would be a future; `question()` would not have been called. To print `s2`, we first have to `s2.await`.
+
+An async block is the simplest way to start an async context and create a future. It is commonly used to create small futures which are only used in one place.
+
+Unfortunately, control flow with async blocks is a little quirky. Because an async block creates a future rather than straightforwardly executing, it behaves more like a function than a regular block with respect to control flow. `break` and `continue` cannot go 'through' an async block like they can with regular blocks; instead you have to use `return`:
+
+```rust,norun
+loop {
+    {
+        if ... {
+            // ok
+            continue;
+        }
+    }
+
+    async {
+        if ... {
+            // not ok
+            // continue;
+
+            // ok - continues with the next execution of the `loop`, though note that if there was
+            // code in the loop after the async block that would be executed.
+            return;
+        }
+    }.await
+}
+```
+
+To implement `break` you would need to test the value of the block (a common idiom is to use [`ControlFlow`](https://doc.rust-lang.org/std/ops/enum.ControlFlow.html) for the value of the block, which also allows use of `?`).
+
+Likewise, `?` inside an async block will terminate execution of the future in the presence of an error, causing the `await`ed block to take the value of the error, but won't exit the surrounding function (like `?` in a regular block would). You'll need another `?` after `await` for that:
+
+```rust,norun
+async {
+    let x = foo()?;   // This `?` only exits the async block, not the surrounding function.
+    consume(x);
+    Ok(())
+}.await?
+```
+
+Annoyingly, this often confuses the compiler since (unlike functions) the 'return' type of an async block is not explicitly stated. You'll probably need to add some type annotations on variables or use turbofished types to make this work, e.g., `Ok::<_, MyError>(())` instead of `Ok(())` in the above example.
+
+A function which returns an async block is pretty similar to an async function. Writing `async fn foo() -> ... { ... }` is roughly equivalent to `fn foo() -> ... { async { ... } }`. In fact, from the caller's perspective they are equivalent, and changing from one form to the other is not a breaking change. Furthermore, you can override one with the other when implementing an async trait (see below). However, you do have to adjust the type, making the `Future` explicit in the async block version: `async fn foo() -> Foo` becomes `fn foo() -> impl Future<Output = Foo>` (you might also need to make other bounds explicit, e.g., `Send` and `'static`).
+
+You would usually prefer the async function version since it is simpler and clearer. However, the async block version is more flexible since you can execute some code when the function is called (by writing it outside the async block) and some code when the result is awaited (the code inside the async block).
+
+
+## Async closures
+
+- closures
+  - coming soon (https://github.com/rust-lang/rust/pull/132706, https://blog.rust-lang.org/inside-rust/2024/08/09/async-closures-call-for-testing.html)
+  - async blocks in closures vs async closures
+
+
+## Lifetimes and borrowing
+
+- Mentioned the static lifetime above
+- Lifetime bounds on futures (`Future + '_`, etc.)
+- Borrowing across await points
+- I don't know, I'm sure there are more lifetime issues with async functions ...
+
 
 ## `Send + 'static` bounds on futures
 
 - Why they're there, multi-threaded runtimes
 - spawn local to avoid them
 - What makes an async fn `Send + 'static` and how to fix bugs with it
 
+
 ## Async traits
 
 - syntax
@@ -36,18 +170,6 @@
 - history and async-trait crate
 
 
-## Async blocks and closures
-
-- async block syntax
-  - what it means
-- using an async block in a function returning a future
-  - subtype of async method
-- closures
-  - coming soon (https://github.com/rust-lang/rust/pull/132706, https://blog.rust-lang.org/inside-rust/2024/08/09/async-closures-call-for-testing.html)
-  - async blocks in closures vs async closures
-- errors in async blocks
-  - https://rust-lang.github.io/async-book/07_workarounds/02_err_in_async_blocks.html
-
 ## Recursion
 
 - Allowed (relatively new), but requires some explicit boxing
@@ -56,10 +178,3 @@
   - https://blog.rust-lang.org/2024/03/21/Rust-1.77.0.html#support-for-recursion-in-async-fn
   - async-recursion macro (https://docs.rs/async-recursion/latest/async_recursion/)
 
-
-## Lifetimes and borrowing
-
-- Mentioned the static lifetime above
-- Lifetime bounds on futures (`Future + '_`, etc.)
-- Borrowing across await points
-- I don't know, I'm sure there are more lifetime issues with async functions ...

src/part-guide/adv-async-await.md

@@ -8,6 +8,9 @@
 - different versions in different runtimes/other crates
   - focus on the Tokio versions
 
+From [comment](https://github.com/rust-lang/async-book/pull/230#discussion_r1829351497): A framing I've started using is that tasks are not the async/await form of threads; it's more accurate to think of them as parallelizable futures. This framing does not match Tokio and async-std's current task design; but both also have trouble propagating cancellation. See parallel_future and tasks are the wrong abstraction for more.
+
+
 ## Join
 
 - Tokio/futures-rs join macro

src/part-guide/concurrency-primitives.md

@@ -21,6 +21,7 @@
 - Taking a future instead of a closure
 - Some example combinators
 - unordered variations
+- StreamGroup
 
 ## Implementing an async iterator