Modifications to the async section (#556)

* Modifications to the async section

* Remove the "Daemon" slide, as it largely duplicates the "Tasks" slide.
  The introduction to the "Control Flow" section mentions tasks as a
  kind of control flow.

* Reorganize the structure in SUMMARY.md to correspond to the directory
  structure.

* Simplify the "Pin" and "Blocking the Executor" slides with steps in
  the speaker notes to demonstrate / fix the issues.

* Rename "join_all" to "Join".

* Simplify some code samples to shorten them, and to print output rather
  than asserting.

* Clarify speaker notes and include more "Try.." suggestions.

* Be consistent about where `async` blocks are introduced (in the
  "Tasks" slide).

* Explain `join` and `select` in prose.

* Fix formatting of section-header slides.

Author: djmitche

src/SUMMARY.md

@@ -229,21 +229,20 @@
 
 ----
 
-- [Async](async.md)
+- [Async Basics](async.md)
   - [async/await](async/async-await.md)
   - [Futures](async/futures.md)
   - [Runtimes](async/runtimes.md)
     - [Tokio](async/runtimes/tokio.md)
   - [Tasks](async/tasks.md)
   - [Async Channels](async/channels.md)
-  - [Futures Control Flow](async/control-flow.md)
-    - [Daemon](async/control-flow/daemon.md)
-    - [Join](async/control-flow/join_all.md)
-    - [Select](async/control-flow/select.md)
-  - [Pitfalls](async/pitfalls.md)
-    - [Blocking the Executor](async/pitfalls/blocking-executor.md)
-    - [Pin](async/pitfalls/pin.md)
-    - [Async Traits](async/pitfalls/async-traits.md)
+- [Control Flow](async/control-flow.md)
+  - [Join](async/control-flow/join.md)
+  - [Select](async/control-flow/select.md)
+- [Pitfalls](async/pitfalls.md)
+  - [Blocking the Executor](async/pitfalls/blocking-executor.md)
+  - [Pin](async/pitfalls/pin.md)
+  - [Async Traits](async/pitfalls/async-traits.md)
 - [Exercises](exercises/day-4/async.md)
 
 # Final Words

src/async/async-await.md

@@ -12,13 +12,11 @@ async fn count_to(count: i32) {
 }
 
 async fn async_main(count: i32) {
-    let future = count_to(count);
-    future.await;
+    count_to(count).await;
 }
 
 fn main() {
-    let future = async_main(10);
-    block_on(future);
+    block_on(async_main(10));
 }
 ```
 
@@ -30,10 +28,10 @@ Key points:
   running operation or any real concurrency in it!
 
 * What is the return type of an async call?
-  * Change `let future = async_main(10);` to `let future: () = async_main(10);`
-    to see the type.
+  * Use `let future: () = async_main(10);` in `main` to see the type.
 
-* The "async" keyword is syntactic sugar. The compiler replaces the return type. 
+* The "async" keyword is syntactic sugar. The compiler replaces the return type
+  with a future. 
 
 * You cannot make `main` async, without additional instructions to the compiler
   on how to use the returned future.
@@ -44,6 +42,7 @@ Key points:
 * `.await` asynchronously waits for the completion of another operation. Unlike
   `block_on`, `.await` doesn't block the current thread.
 
-* `.await` can only be used inside an `async` block. 
+* `.await` can only be used inside an `async` function (or block; these are
+  introduced later). 
 
 </details>

src/async/channels.md

@@ -1,6 +1,6 @@
 # Async Channels
 
-Multiple Channels crates have support for `async`/`await`. For instance `tokio` channels:
+Several crates have support for `async`/`await`. For instance `tokio` channels:
 
 ```rust,editable,compile_fail
 use tokio::sync::mpsc::{self, Receiver};
@@ -12,6 +12,8 @@ async fn ping_handler(mut input: Receiver<()>) {
         count += 1;
         println!("Received {count} pings so far.");
     }
+
+    println!("ping_handler complete");
 }
 
 #[tokio::main]
@@ -35,9 +37,11 @@ async fn main() {
 * Overall, the interface is similar to the `sync` channels as seen in the
   [morning class](concurrency/channels.md).
 
-* The `Flume` crate has channels that implement both `sync` and `async` `send`
-  and `recv`. This can be convenient for complex application with both IO and
-  heavy CPU processing tasks.
+* Try removing the `std::mem::drop` call. What happens? Why?
+
+* The [Flume](https://docs.rs/flume/latest/flume/) crate has channels that
+  implement both `sync` and `async` `send` and `recv`. This can be convenient
+  for complex applications with both IO and heavy CPU processing tasks.
 
 * What makes working with `async` channels preferable is the ability to combine
   them with other `future`s to combine them and create complex control flow.

src/async/control-flow.md

@@ -1,10 +1,7 @@
 # Futures Control Flow
 
 Futures can be combined together to produce concurrent compute flow graphs. We
-will cover multiple common operations:
+have already seen tasks, that function as independent threads of execution.
 
-----
-
-- [Daemon](control-flow/daemon.md)
-- [Join](control-flow/join_all.md)
+- [Join](control-flow/join.md)
 - [Select](control-flow/select.md)

src/async/control-flow/daemon.md

@@ -1,13 +1,8 @@
-# join_all
+# Join
 
-Futures can be combined together to produce concurrent compute flow graphs.
-
-## Run a group of futures concurrently until they all resolve: `join_all`
-
-### Equivalents:
-
-- JS: `Promise.all`
-- Python: `asyncio.gather`
+A join operation waits until all of a set of futures are ready, and
+returns a collection of their results. This is similar to `Promise.all` in
+JavaScript or `asyncio.gather` in Python.
 
 ```rust,editable,compile_fail
 use anyhow::Result;
@@ -38,11 +33,19 @@ async fn main() {
 
 <details>
 
-* `join_all` should soon be stabilized as part of the standard library in `std::future`.
-* For multiple futures of disjoint types, you can use `join!` but you must know how many futures you will have at compile time.
-* You can also combine `join_all` with `join!` for instance to join all requests to an http service as well as a database query.
-* The risk of `join` is that one of the future could never resolve, this would cause your program to stall. 
-* Try adding a timeout to the future.
+Copy this example into your prepared `src/main.rs` and run it from there.
+
+* For multiple futures of disjoint types, you can use `std::future::join!` but
+  you must know how many futures you will have at compile time. This is
+  currently in the `futures` crate, soon to be stabilised in `std::future`.
+
+* The risk of `join` is that one of the futures may never resolve, this would
+  cause your program to stall. 
+
+* You can also combine `join_all` with `join!` for instance to join all requests
+  to an http service as well as a database query.
+
+* Try adding a timeout to the future, using `futures::join!`.
 
 </details>
 

src/async/control-flow/join_all.md renamed to src/async/control-flow/join.md

@@ -1,11 +1,13 @@
 # Select
 
-## Run multiple futures concurrently until the first one resolves
+A select operation waits until any of a set of futures is ready, and responds to
+that future's result. In JavaScript, this is similar to `Promise.race`. In
+Python, it compares to `asyncio.wait(task_set,
+return_when=asyncio.FIRST_COMPLETED)`.
 
-### Equivalents:
-
-- JS: `Promise.race`
-- Python: `asyncio.new_event_loop().run_until_complete(asyncio.wait(task_set, return_when=asyncio.FIRST_COMPLETED))`
+This is usually a macro, similar to match, with each arm of the form `pattern =
+future => statement`. When the future is ready, the statement is executed with the
+variable bound to the future's result.
 
 ```rust,editable,compile_fail
 use tokio::sync::mpsc::{self, Receiver};
@@ -32,32 +34,42 @@ async fn main() {
     let (cat_sender, cat_receiver) = mpsc::channel(32);
     let (dog_sender, dog_receiver) = mpsc::channel(32);
     tokio::spawn(async move {
-        sleep(Duration::from_secs(10)).await;
+        sleep(Duration::from_millis(500)).await;
         cat_sender
             .send(String::from("Felix"))
             .await
             .expect("Failed to send cat.");
     });
     tokio::spawn(async move {
-        sleep(Duration::from_secs(5)).await;
+        sleep(Duration::from_millis(50)).await;
         dog_sender
             .send(String::from("Rex"))
             .await
-            .expect("Failed to send cat.");
+            .expect("Failed to send dog.");
     });
 
     let winner = first_animal_to_finish_race(cat_receiver, dog_receiver)
         .await
         .expect("Failed to receive winner");
 
-    assert_eq!(winner, Animal::Dog {name: String::from("Rex")});
+    println!("Winner is {winner:?}");
 }
 ```
 
 <details>
 
-* In this example, we have a race between a cat and a dog. `first_animal_to_finish_race` listens to both channels and will pick whichever arrives first. Since the dog takes 5 seconds, it wins against the cat that take 10 seconds.
-* You can use `oneshot` channels in this example as the channels are supposed to receive only one `send`.
-* You can try adding more contestants to the race and return a leaderboard. Also, you can add a deadline after which contestants get eliminated.
+* In this example, we have a race between a cat and a dog.
+  `first_animal_to_finish_race` listens to both channels and will pick whichever
+  arrives first. Since the dog takes 50ms, it wins against the cat that
+  take 500ms seconds.
+
+* You can use `oneshot` channels in this example as the channels are supposed to
+  receive only one `send`.
+
+* Try adding a deadline to the race, demonstrating selecting different sorts of
+  futures.
+
+* Note that `select!` consumes the futures it is given, and is easiest to use
+  when every execution of `select!` creates new futures.
 
 </details>

src/async/control-flow/select.md

@@ -1,9 +1,9 @@
 # Futures
 
-[Future](https://doc.rust-lang.org/nightly/src/core/future/future.rs.html#37)
+[`Future`](https://doc.rust-lang.org/std/future/trait.Future.html)
 is a trait, implemented by objects that represent an operation that may not be
-complete yet. A future can be polled, and `poll` returns either
-`Poll::Ready(result)` or `Poll::Pending`.
+complete yet. A future can be polled, and `poll` returns a
+[`Poll`](https://doc.rust-lang.org/std/task/enum.Poll.html).
 
 ```rust
 use std::pin::Pin;
@@ -20,18 +20,17 @@ pub enum Poll<T> {
 }
 ```
 
-An async function returns an `impl Future`, and an async block evaluates to an
-`impl Future`. It's also possible (but uncommon) to implement `Future` for your
-own types. For example, the `JoinHandle` returned from `tokio::spawn` implements
-`Future` to allow joining to it.
+An async function returns an `impl Future`. It's also possible (but uncommon) to
+implement `Future` for your own types. For example, the `JoinHandle` returned
+from `tokio::spawn` implements `Future` to allow joining to it.
 
-The `.await` keyword, applied to a Future, causes the current async function or
-block to pause until that Future is ready, and then evaluates to its output.
+The `.await` keyword, applied to a Future, causes the current async function to
+pause until that Future is ready, and then evaluates to its output.
 
 <details>
 
-* The `Future` and `Poll` types are conceptually quite simple, and implemented as
-  such in `std::task`.
+* The `Future` and `Poll` types are implemented exactly as shown; click the
+  links to show the implementations in the docs.
 
 * We will not get to `Pin` and `Context`, as we will focus on writing async
   code, rather than building new async primitives. Briefly:

src/async/futures.md

@@ -2,8 +2,6 @@
 
 Async / await provides convenient and efficient abstraction for concurrent asynchronous programming. However, the async/await model in Rust also comes with its share of pitfalls and footguns. We illustrate some of them in this chapter:
 
----
-
 - [Blocking the Executor](pitfalls/blocking-executor.md)
 - [Pin](pitfalls/pin.md)
 - [Async Traits](pitfall/async-traits.md)

src/async/pitfalls.md

@@ -6,6 +6,7 @@ The crate [async_trait](https://docs.rs/async-trait/latest/async_trait/) provide
 
 ```rust,editable,compile_fail
 use async_trait::async_trait;
+use std::time::Instant;
 use tokio::time::{sleep, Duration};
 
 #[async_trait]
@@ -26,8 +27,11 @@ impl Sleeper for FixedSleeper {
 
 async fn run_all_sleepers_multiple_times(sleepers: Vec<Box<dyn Sleeper>>, n_times: usize) {
     for _ in 0..n_times {
+        println!("running all sleepers..");
         for sleeper in &sleepers {
+            let start = Instant::now();
             sleeper.sleep().await;
+            println!("slept for {}ms", start.elapsed().as_millis());
         }
     }
 }
@@ -44,7 +48,11 @@ async fn main() {
 
 <details>  
 
+* `async_trait` is easy to use, but note that it's using heap allocations to
+  achieve this, which has performance implications.
+
 * Try creating a new sleeper struct that will sleep for a random amount of time and adding it to the Vec.
-* Try making the `sleep` call mutable.
-* Try adding an associated type for the return value that would return how much time was actually slept.
-</details>
+
+* Try making the `sleep` call take `&mut self`.
+
+</details>