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.
This commit is contained in:
Chris Krycho 2024-04-23 17:26:07 -06:00
parent 54bc9ee0d1
commit 29bf745eac
2 changed files with 50 additions and 4 deletions

View File

@ -241,6 +241,7 @@ Hello, async!
```
Now, thats 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

View File

@ -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 lets 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