Add an "async" session (#496)

* beginning of an Async section

* address review comments

* Add futures page (#497)

NOTE: `mdbook test` does not allow code samples to reference other crates, so
they must be marked as `compile_fail`; see #175.

* Add Runtimes & Tasks (#522)

These concepts are closely related, and there's not much else to know
about runtimes other than "they exist".

This removes the bit about futures being "inert" because it doesn't
really lead anywhere.

* Async chapter (#524)

* Add async channels chapter

* Async control flow

* Async pitfalls

* Separate in multiple chapters + add daemon section

* Merge reentering threads in blocking-executor

* async_trait

* Async fixes (#546)

* Async: some ideas for simplifying the content (#550)

* Simplify the async-await slide
* Shorten futures and move it up
* Add a page on Tokio

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

* Add a note on async trait (#558)

---------

Co-authored-by: sakex <[email protected]>
Co-authored-by: rbehjati <[email protected]>

src/SUMMARY.md

@@ -226,8 +226,24 @@
     - [With Java](android/interoperability/java.md)
 - [Exercises](exercises/day-4/android.md)
 
-# Async (temp until issue181 is closed)
+# Day 4: Afternoon (Async)
 
+----
+
+- [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)
+- [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/elevator.md)
 
 # Final Words

src/async.md

@@ -0,0 +1,25 @@
+# Async Rust
+
+"Async" is a concurrency model where multiple tasks are executed concurrently by
+executing each task until it would block, then switching to another task that is
+ready to make progress. The model allows running a larger number of tasks on a
+limited number of threads. This is because the per-task overhead is typically
+very low and operating systems provide primitives for efficiently identifying
+I/O that is able to proceed.
+
+Rust's asynchronous operation is based on "futures", which represent work that
+may be completed in the future. Futures are "polled" until they signal that
+they are complete.
+
+Futures are polled by an async runtime, and several different runtimes are
+available.
+
+## Comparisons
+
+ * Python has a similar model in its `asyncio`. However, its `Future` type is
+   callback-based, and not polled. Async Python programs require a "loop",
+   similar to a runtime in Rust.
+
+ * JavaScript's `Promise` is similar, but again callback-based. The language
+   runtime implements the event loop, so many of the details of Promise
+   resolution are hidden.

src/async/async-await.md

@@ -0,0 +1,48 @@
+# `async`/`await`
+
+At a high level, async Rust code looks very much like "normal" sequential code:
+
+```rust,editable,compile_fail
+use futures::executor::block_on;
+
+async fn count_to(count: i32) {
+    for i in 1..=count {
+        println!("Count is: {i}!");
+    }
+}
+
+async fn async_main(count: i32) {
+    count_to(count).await;
+}
+
+fn main() {
+    block_on(async_main(10));
+}
+```
+
+<details>
+
+Key points:
+
+* Note that this is a simplified example to show the syntax. There is no long
+  running operation or any real concurrency in it!
+
+* What is the return type of an async call?
+  * Use `let future: () = async_main(10);` in `main` to see the 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.
+
+* You need an executor to run async code. `block_on` blocks the current thread
+  until the provided future has run to completion. 
+
+* `.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` function (or block; these are
+  introduced later). 
+
+</details>

src/async/channels.md

@@ -0,0 +1,49 @@
+# Async Channels
+
+Several crates have support for `async`/`await`. For instance `tokio` channels:
+
+```rust,editable,compile_fail
+use tokio::sync::mpsc::{self, Receiver};
+
+async fn ping_handler(mut input: Receiver<()>) {
+    let mut count: usize = 0;
+
+    while let Some(_) = input.recv().await {
+        count += 1;
+        println!("Received {count} pings so far.");
+    }
+
+    println!("ping_handler complete");
+}
+
+#[tokio::main]
+async fn main() {
+    let (sender, receiver) = mpsc::channel(32);
+    let ping_handler_task = tokio::spawn(ping_handler(receiver));
+    for i in 0..10 {
+        sender.send(()).await.expect("Failed to send ping.");
+        println!("Sent {} pings so far.", i + 1);
+    }
+
+    std::mem::drop(sender);
+    ping_handler_task.await.expect("Something went wrong in ping handler task.");
+}
+```
+
+<details>
+
+* Change the channel size to `3` and see how it affects the execution.
+
+* Overall, the interface is similar to the `sync` channels as seen in the
+  [morning class](concurrency/channels.md).
+
+* 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.
+
+</details>

src/async/control-flow.md

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

src/async/control-flow/join.md

@@ -0,0 +1,51 @@
+# Join
+
+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;
+use futures::future;
+use reqwest;
+use std::collections::HashMap;
+
+async fn size_of_page(url: &str) -> Result<usize> {
+    let resp = reqwest::get(url).await?;
+    Ok(resp.text().await?.len())
+}
+
+#[tokio::main]
+async fn main() {
+    let urls: [&str; 4] = [
+        "https://google.com",
+        "https://httpbin.org/ip",
+        "https://play.rust-lang.org/",
+        "BAD_URL",
+    ];
+    let futures_iter = urls.into_iter().map(size_of_page);
+    let results = future::join_all(futures_iter).await;
+    let page_sizes_dict: HashMap<&str, Result<usize>> =
+        urls.into_iter().zip(results.into_iter()).collect();
+    println!("{:?}", page_sizes_dict);
+}
+```
+
+<details>
+
+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/select.md

@@ -0,0 +1,75 @@
+# Select
+
+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)`.
+
+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};
+use tokio::time::{sleep, Duration};
+
+#[derive(Debug, PartialEq)]
+enum Animal {
+    Cat { name: String },
+    Dog { name: String },
+}
+
+async fn first_animal_to_finish_race(
+    mut cat_rcv: Receiver<String>,
+    mut dog_rcv: Receiver<String>,
+) -> Option<Animal> {
+    tokio::select! {
+        cat_name = cat_rcv.recv() => Some(Animal::Cat { name: cat_name? }),
+        dog_name = dog_rcv.recv() => Some(Animal::Dog { name: dog_name? })
+    }
+}
+
+#[tokio::main]
+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_millis(500)).await;
+        cat_sender
+            .send(String::from("Felix"))
+            .await
+            .expect("Failed to send cat.");
+    });
+    tokio::spawn(async move {
+        sleep(Duration::from_millis(50)).await;
+        dog_sender
+            .send(String::from("Rex"))
+            .await
+            .expect("Failed to send dog.");
+    });
+
+    let winner = first_animal_to_finish_race(cat_receiver, dog_receiver)
+        .await
+        .expect("Failed to receive winner");
+
+    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 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/futures.md

@@ -0,0 +1,45 @@
+# Futures
+
+[`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 a
+[`Poll`](https://doc.rust-lang.org/std/task/enum.Poll.html).
+
+```rust
+use std::pin::Pin;
+use std::task::Context;
+
+pub trait Future {
+    type Output;
+    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output>;
+}
+
+pub enum Poll<T> {
+    Ready(T),
+    Pending,
+}
+```
+
+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 to
+pause until that Future is ready, and then evaluates to its output.
+
+<details>
+
+* 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:
+
+  * `Context` allows a Future to schedule itself to be polled again when an
+    event occurs.
+
+  * `Pin` ensures that the Future isn't moved in memory, so that pointers into
+    that future remain valid. This is required to allow references to remain
+    valid after an `.await`.
+
+</details>

src/async/pitfalls.md

@@ -0,0 +1,7 @@
+# Pitfalls of async/await
+
+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)