Merge branch 'issue181' into async-chapter

Author: sakex

src/SUMMARY.md

@@ -232,10 +232,7 @@
 - [Async](async.md)
   - [async/await](async/async-await.md)
   - [Async Blocks](async/async-blocks.md)
-  - Futures
-  - Executors
-  - Polling
-  - Pin
+  - [Futures](async/futures.md)
   - [Async Channels](async/channels.md)
   - [Futures Control Flow](async/control-flow.md)
 - [Exercises](exercises/day-4/async.md)

src/async/async-await.md

@@ -2,11 +2,11 @@
 
 At a high level, async Rust code looks very much like "normal" sequential code:
 
-```rust,editable
+```rust,editable,compile_fail
 use tokio::time;
 
-async fn count_to(i: i32) {
-    for i in 1..10 {
+async fn count_to(count: i32) {
+    for i in 1..=count {
         println!("Count in task: {i}!");
         time::sleep(time::Duration::from_millis(5)).await;
     }

src/async/async-blocks.md

@@ -3,7 +3,7 @@
 Similar to closures, a snippet of async code can be included inline in another
 function with an async block:
 
-```rust, editable
+```rust,editable,compile_fail
 use tokio::{time, task};
 
 #[tokio::main]

src/async/channels.md

@@ -2,13 +2,12 @@
 
 Multiple Channels crates have support for `async`/`await` read and write. For instance `tokio` channels:
 
-
-```rust,editable
+```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.");
@@ -22,7 +21,7 @@ async fn main() {
     for _ in 0..10 {
         sender.send(()).await.expect("Failed to send ping.");
     }
-    
+
     std::mem::drop(sender);
     ping_handler_task.await.expect("Something went wrong in ping handler task.");
 }

src/async/control-flow.md

@@ -10,7 +10,7 @@ We will demonstrate here a non-exhaustive array of common operations:
 - JS: `Promise.all`
 - Python: `asyncio.gather`
 
-```rust,editable
+```rust,editable,compile_fail
 use anyhow::Result;
 use futures::future;
 use reqwest;
@@ -44,7 +44,7 @@ async fn main() {
 - JS: `Promise.race`
 - Python: `asyncio.new_event_loop().run_until_complete(asyncio.wait(task_set, return_when=asyncio.FIRST_COMPLETED))`
 
-```rust,editable
+```rust,editable,compile_fail
 use anyhow::Result;
 use tokio::sync::mpsc::{self, Receiver, Sender};
 use tokio::time::{sleep, Duration};
@@ -107,7 +107,7 @@ async fn main() {
 
 ## Iterate over multiple channels with a timeout: `select` with `pin`
 
-```rust,editable
+```rust,editable,compile_fail
 use anyhow::Result;
 use tokio::sync::mpsc::{self, Receiver, Sender};
 use tokio::time::{sleep, Duration};

src/async/futures.md

@@ -0,0 +1,72 @@
+# 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() {
+    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
+`Poll::Ready(result)` or `Poll::Pending`.
+
+```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`, 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.
+
+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.
+
+An important difference from other languages is that a Future is inert: it does
+not do anything until it is polled.
+
+<details>
+
+* Run the example and look at the error message. `_: () = ..` is a common
+  technique for getting the type of an expression. Try adding a `.await` in
+  `main`.
+
+* The `Future` and `Poll` types are conceptually quite simple, and implemented as
+  such in `std::task`.
+
+* 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>