beginning of an Async section

Author: djmitche

src/SUMMARY.md

@@ -225,6 +225,21 @@
     - [With Java](android/interoperability/java.md)
 - [Exercises](exercises/day-4/android.md)
 
+# Day 4: Afternoon (Async)
+
+----
+
+- [Async](async.md)
+  - [async/await](async/async-await.md)
+  - [Async Blocks](async/async-blocks.md)
+  - Futures
+  - Executors
+  - Polling
+  - Pin
+  - Channels
+  - Select
+- [Exercises](exercises/day-4/async.md)
+
 # Final Words
 
 - [Thanks!](thanks.md)

src/async.md

@@ -0,0 +1,17 @@
+# 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 scales to higher concurrency than threads
+because the per-task overhead is typically very low and operating systems
+provide means of efficiently selecting tasks that can make progress.
+
+## 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 an executor 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,52 @@
+# `async`/`await`
+
+At a high level, async Rust code looks very much like "normal" sequential code:
+
+```rust,editable
+use tokio::time;
+
+async fn count_to(i: i32) {
+    for i in 1..10 {
+        println!("Count in task: {i}!");
+        time::sleep(time::Duration::from_millis(5)).await;
+    }
+}
+
+#[tokio::main]
+async fn main() {
+    tokio::spawn(count_to(10));
+
+    for i in 1..5 {
+        println!("Main task: {i}");
+        time::sleep(time::Duration::from_millis(5)).await;
+    }
+}
+```
+
+<details>
+
+Key points:
+
+* Tokio is one of several async runtimes available for Rust.
+
+* The function is decorated with the "async" keyword to indicate that it is async.  The
+  `tokio::main` macro invocation is a convenience to wrap the `main` function as a task.
+
+* The `spawn` function creates a new, concurrent "task", just like spawning a thread.
+
+* Whenever a task would block, we add an `.await` which returns control to the runtime until the
+  blocking operation is ready to proceed.
+
+Further exploration:
+
+* Why does `count_to` not (usually) get to 10? This is an example of async cancellation.
+  `tokio::spawn` returns a handle which can be awaited to wait until it finishes.
+
+* Try `count_to(10).await` instead of spawning.
+
+* Try importing `tokio::join` and using it to join multiple handles.
+
+Note that the Rust playground does not allow network connections, so examples like making HTTP
+requests are not possible.
+
+</details>

src/async/async-blocks.md

@@ -0,0 +1,34 @@
+# Async Blocks
+
+Similar to closures, a snippet of async code can be included inline in another
+function with an async block:
+
+```rust, editable
+use tokio::{time, task};
+
+#[tokio::main]
+async fn main() {
+    let mut joinset = task::JoinSet::new();
+
+    for i in 1..5 {
+        joinset.spawn(async move {
+            println!("task {i} starting");
+            time::sleep(time::Duration::from_millis(i)).await;
+            println!("task {i} done");
+            format!("hello from task {i}")
+        });
+    }
+
+    while let Some(res) = joinset.join_next().await {
+        let greeting = res.unwrap();
+        println!("task joined with result: {greeting}");
+    }
+}
+
+<details>
+
+An async block is similar to a closure, but does not take any arguments.
+
+Its return value is a Future, which is described on the next slide.
+
+</details>

src/exercises/day-4/async.md

@@ -0,0 +1,3 @@
+# Exercises
+
+TBD