Skip to content

Commit

Permalink
Ch. 17: Introduce runtimes and the trpl crate
Browse files Browse the repository at this point in the history
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.
  • Loading branch information
chriskrycho authored and carols10cents committed Apr 30, 2024
1 parent 71d92ec commit fdb3794
Show file tree
Hide file tree
Showing 2 changed files with 50 additions and 4 deletions.
3 changes: 2 additions & 1 deletion src/ch17-01-tasks.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
51 changes: 48 additions & 3 deletions src/ch17-02.md
Original file line number Diff line number Diff line change
@@ -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

0 comments on commit fdb3794

Please sign in to comment.