Add an "async" session

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)