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