From fdb3794e2af67a037493e54259be98442b908f59 Mon Sep 17 00:00:00 2001
From: Chris Krycho <hello@chriskrycho.com>
Date: Tue, 23 Apr 2024 17:26:07 -0600
Subject: [PATCH] Ch. 17: Introduce runtimes and the `trpl` crate

Add a fair bit more material about the `futures` executor and why we
might prefer to use something else. With that motivation in place, have
the readers add our `trpl` crate. (We can of course rename that crate,
but it does the job for now.) Use it to get the equivalent of
`#[tokio::main]` equivalent and incorporate it into an example.
---
 src/ch17-01-tasks.md |  3 ++-
 src/ch17-02.md       | 51 +++++++++++++++++++++++++++++++++++++++++---
 2 files changed, 50 insertions(+), 4 deletions(-)

diff --git a/src/ch17-01-tasks.md b/src/ch17-01-tasks.md
index 701a720bb1..70ed2f2647 100644
--- a/src/ch17-01-tasks.md
+++ b/src/ch17-01-tasks.md
@@ -241,6 +241,7 @@ Hello, async!
 ```
 
 Now, that’s a lot of work to just print a string, but we have laid some key
-foundations for working with async and await in Rust.
+foundations for working with async-await in Rust! Now that you know the basics
+of how futures work, and the
 
 [impl-trait]: ch10-02-traits.html#traits-as-parameters
diff --git a/src/ch17-02.md b/src/ch17-02.md
index 75d4dcaa65..80c1a6f582 100644
--- a/src/ch17-02.md
+++ b/src/ch17-02.md
@@ -1,4 +1,49 @@
 The executor from `futures` we used in the previous section is intentionally
-quite limited. It works well, but if you are going to build a real-world
-application, you will want to use the executor from one of the *other* runtimes
-in the Rust ecosystem.
+quite limited. It works quite well, but if you are going to build a real-world
+application, you will likely want to use the executor from one of the *other*
+runtimes in the Rust ecosystem.
+
+For the rest of the chapter, we will be using [Tokio][tokio], which is the most
+widely used async runtime, especially (but not only!) for web applications.
+
+> Note: There are other great options out there, too, and they may be more
+> suitable for your purposes, so this is not at all saying Tokio is better than
+> the alternatives.
+
+To keep this chapter focused on learning async-await, rather than juggling parts
+of the ecosystem, we have created the `trpl` crate. (`trpl` is short for “The
+Rust Programming Language”). It re-exports all the types, traits, and functions
+you will need, and in a couple cases wires up a few things for you which are
+less relevant to the subject of the book. There is no magic involved, though! If
+you want to understand what the crate does, we encourage you to check out [its
+source code][crate-source]. You will be able to see what crate each re-export
+comes from, and we have left extensive comments explaining what the handful of
+helper functions we supply are doing.
+
+For now, go ahead and add the dependency to your `hello-async` project:
+
+```console
+$ cargo add trpl
+```
+
+Okay, now let’s start exploring . Going forward, we will use a new `async_main`
+macro so that we can use `async fn` with a `main` function. Under the hood, this
+little utility macro from Tokio sets up the Tokio runtime and wires up a call
+kind of like we saw with `futures::executor::block_on` in the previous section.
+
+```rust
+use trpl::async_main;
+
+#[async_main]
+async fn main() {
+    async {
+        println!("Hello, world!");
+    }.await;
+}
+```
+
+Now we can use `async` blocks directly in `main` and not worry about wiring up
+the runtime ourselves.
+
+[tokio]: https://tokio.rs
+[crate-source]: TODO