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

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

Author: rbehjati

src/SUMMARY.md

@@ -231,10 +231,10 @@
 
 - [Async](async.md)
   - [async/await](async/async-await.md)
-  - [Async Blocks](async/async-blocks.md)
   - [Futures](async/futures.md)
   - [Runtimes](async/runtimes.md)
-  - [Tasks](async/tasks.md)ures](async/futures.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)

src/async/async-await.md

@@ -3,50 +3,47 @@
 At a high level, async Rust code looks very much like "normal" sequential code:
 
 ```rust,editable,compile_fail
-use tokio::time;
+use futures::executor::block_on;
 
 async fn count_to(count: i32) {
     for i in 1..=count {
-        println!("Count in task: {i}!");
-        time::sleep(time::Duration::from_millis(5)).await;
+        println!("Count is: {i}!");
     }
 }
 
-#[tokio::main]
-async fn main() {
-    tokio::spawn(count_to(10));
+async fn async_main(count: i32) {
+    let future = count_to(count);
+    future.await;
+}
 
-    for i in 1..5 {
-        println!("Main task: {i}");
-        time::sleep(time::Duration::from_millis(5)).await;
-    }
+fn main() {
+    let future = async_main(10);
+    block_on(future);
 }
 ```
 
 <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.
+* Note that this is a simplified example to show the syntax. There is no long
+  running operation or any real concurrency in it!
 
-* Whenever a task would block, we add an `.await` which returns control to the runtime until the
-  blocking operation is ready to proceed.
+* 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.
 
-Further exploration:
+* The "async" keyword is syntactic sugar. The compiler replaces the return type. 
 
-* 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.
+* You cannot make `main` async, without additional instructions to the compiler
+  on how to use the returned future.
 
-* Try `count_to(10).await` instead of spawning.
+* You need an executor to run async code. `block_on` blocks the current thread
+  until the provided future has run to completion. 
 
-* Try importing `tokio::join` and using it to join multiple handles.
+* `.await` asynchronously waits for the completion of another operation. Unlike
+  `block_on`, `.await` doesn't block the current thread.
 
-Note that the Rust playground does not allow network connections, so examples like making HTTP
-requests are not possible.
+* `.await` can only be used inside an `async` block. 
 
 </details>

src/async/async-blocks.md

@@ -28,6 +28,12 @@ async fn main() {
 
 <details>
 
-* It is good practice to make your deamons exit because some other blocking task might depend on them. Which would prevent your main thread from ever closing. You can use a `oneshot` channel to signal the task to terminate. You can also use the `ctrl+c` signal handler from `tokio` as an interrupt signal.
+* An async block is similar to a closure, but does not take any arguments. Its
+  return value is a Future, similar to `async fn`. 
+
+* It is good practice to make your deamons exit because some other blocking
+  task might depend on them. Which would prevent your main thread from ever
+  closing. You can use a `oneshot` channel to signal the task to terminate. You
+  can also use the `ctrl+c` signal handler from `tokio` as an interrupt signal.
 
 </details>

src/async/control-flow/daemon.md

@@ -1,28 +1,5 @@
 # Futures
 
-What is the type of an async operation?
-
-```rust,editable,compile_fail
-use tokio::time;
-
-async fn count_to(count: i32) -> i32 {
-    for i in 1..=count {
-        println!("Count in task: {i}!");
-        time::sleep(time::Duration::from_millis(5)).await;
-    }
-    count
-}
-
-#[tokio::main]
-async fn main() {
-    println!("Final count is: {}!", count_to(13).await);
-
-    // Uncomment the following line to see the return type of the async call.
-    // let _: () = count_to(13);
-
-}
-```
-
 [Future](https://doc.rust-lang.org/nightly/src/core/future/future.rs.html#37)
 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

src/async/futures.md

@@ -0,0 +1,49 @@
+# Tokio
+
+
+Tokio provides: 
+
+* A multi-threaded runtime for executing asynchronous code.
+* An asynchronous version of the standard library.
+* A large ecosystem of libraries.
+
+```rust,editable,compile_fail
+use tokio::time;
+
+async fn count_to(count: i32) {
+    for i in 1..=count {
+        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>
+
+* With the `tokio::main` macro we can now make `main` async.
+
+* The `spawn` function creates a new, concurrent "task".
+
+* Note: `spawn` takes a `Future`, you don't call `.await` on `count_to`.
+
+**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.
+
+</details>