We will primarily just be re-exporting this, though we may also have a
couple cases where we choose to implement something small around it.

1. Introduce an integration tests crate. Structure it the way people
   *should* for large crates (although this is not that) and document
   why, including linking to a relevant post.
2. Add a basic integration test that verifies the re-export works as it
   should. (This is not exactly rocket science, but we want to make sure
   these things don’t just stop working on accident.)

An open question that remains here: do we want some structure to the
crate beyond the top level re-exports? My inclination at this moment is:
no, because we don’t have any *motivation* for that, and naming things
is difficult. (We cannot do `trpl::async`, for example, because `async`
is a keyword!)

- 17.00: Introduction to the conceptual machinery. This is very nascent
  but has some decent bones.
- 17.01: Trying to get at the foundations for tasks, laziness, etc.;
  this is *especially* incomplete.
- 17.02: Just a paragraph I do not want to lose, which I think *will*
  be useful… eventually.

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.

Move up the installation of the futures crate: get the initial example
compiling as soon as possible (even though it is just "Hello, world!")
and *then* explain what was going on.

- Update the instructions to install `trpl` instead of `futures`, and
  move the introductory text there.
- Update the note about Tokio in 17.02 to describe both `futures` and
  `tokio`.

- Explicitly section out the discussions of async functions and blocks
  and the associated `async` and `.await` syntax from defining `Future`
  and explaining how it works.
- Also a bunch of small phrasing tweaks.

- Tie off the discussion about needing a runtime so that it is clear
  what is needed in `main` and therefore why `main` cannot natively be
  `async` itself.
- Correct the description of what `.await` compiles to.
- Extend the note about the “under the hood” bits: mention generators so
  people know what to go looking for if they are curious.
- Rewrite the existing introduction of the `#[async_main]` macro to lean
  on the material now covered in the previous chapter.

Keep both references, but make the first one a simple definition, and
the second one the “ah, now we can make sense of that definition”.

Re-exporting the macro does not work unless you have `tokio` as a direct
dependency, because its expansion is in terms of Tokio doc-hidden items.

Add some listings which I can actually run, with `TODO` paths in them
since I do not know what the numbers will be, since I have not actually
finished with §0 or §1 yet!

Also rename the files to match their actual titles now that I know them.
Or at least: know a good first pass for them.

- Introduce the relevant supporting features in `trpl`.
- Add a couple listings to show how things do or do not work.

- Incorporate a good discusion of the need to make sure that the `tx`
  in this example gets dropped.
- Add more listings which show borrowing vs. moving a `tx`, covering
  the full territory in that example.
- Add and test more re-exports in `trpl`.

I made a conscious choice here *not* to use `future::join_all()` because
that ends up getting into a discussion of `Pin`. I left a TODO item here
for now because I think it is probably worth getting into, and that
could be a good thing to transition to *after* this section.

It should manage its own dependencies.

Wherever it makes sense to elide these for the sake of clarity, do so!

I am not 100% sure we will keep these, but right now they feel useful for
helping see how `async` can help solve some of these problems.

This lets me combine the examples of trying to get data “out” with the
existing network socket example, rather than introducing yet another
imaginary API, and gives us a final API that looks much closer to what
users will actually see with a real world socket.

§03 is the current place I expect to tackle the distinctions between
threads, tasks, and futures, and is therefore a reasonable home for a
brief discussion on these two big ideas, I think?

- Move the heading out from §03.
- Add this to the summary.

- Gradually build up to the full thing, rather than dumping it all at
  once at the start.
- Show several more “false starts” along the way, using them to teach
  a couple key ideas about async and control flow.
- Update the listings to have their actual expected numbers.

Up to this point, the chapter has stuck to `join` and `join3`, as simple
function-based APIs. The `join_all` API is obviously more convenient
than those *if you can use it*, but being able to use it requires having
something which `impl Iterator` of a given type, and therefore demands a
homogeneous type, which motivates introducing `Box::pin`.

That in turn is quite annoying to work with and requires `Output =
<same>` for all the futures in the collection, because of how `join_all`
is typed (Rust does not have the ability to do do variadic types, which
is what would be necessary for `join_all` to work the way we might
want). Thus, we get a motivation for `futures::join!`, which unlike
`join_all` *can* work with heterogeneous types.

This fills out a fair bit of the text here and adds a lot of the listing
support, and outlines what remains to do text-wise.

This does not yet actually *explain* either of them, but it gets us to
the point where an explanation is well-motivated and can make some
sense, and it (more or less successfully) covers the set of errors that
gets us to that point.

This is (a) far from perfect and (b) far from done, but it represents a
useful increment of work and includes a bunch of notes for where to go
next with this quite tricky section.

listings/ch17-async-await/listing-17-13/src/main.rs JJ:     M
listings/ch17-async-await/listing-17-14/src/main.rs JJ:     M
src/ch17-02-concurrency-with-async.md

This also has the setup for showing `select`, but currently jumps ahead
to showing a `timeout` example.

Create a `trpl::race` function which simplifies the `select` API by
ignoring the future which resolves second. Use the `race` function to
show how you can implement an even simpler `timeout` function on top of
it, i.e. showing how futures can compose nicely. With that in place,
there is enough to be able to “work up to it” in the body of the text.

This is good to know about, but has significant problems, mostly down to
the issues Niko covers in [this post][post] regarding the way ownership
and closures interact. See [this Stack Overflow answer][so], which
applies that dynamic specifically to a `retry` implementation which
happens to be more or less identical to what I built here!

[post]: https://smallcultfollowing.com/babysteps/blog/2023/05/09/giving-lending-and-async-closures/
[answer]: https://stackoverflow.com/questions/75533630/how-to-write-a-retry-function-in-rust-that-involves-async

As described in the parent commit, what I have here technically works
but is adjacent to an area of the language which does *not* yet work as
well as we might hope: closures which involve async. Since even the
smallest refactor here (extracting the future *or* the closure to a
standalone binding) breaks the code, best to remove it entirely in favor
of some other example of composing futures together.

backout of commit d5ed8de

- Update the implementation for `race` to use `futures::future::Either`
  instead of duplicating the type, and update the test not to try to use
  equality.
- Add a `pub use` for `tokio::task::yield_now`.

…and fix a bunch of the listing references and make some word choice and
sentence structure improvements along the way to boot.

Fix some infelicitous wording along the way, and leave a TODO item to
come back to for making more sense out of the text as it stands at the
conclusion of the chapter.

- Actually show “slow” work with interleaved await points in examples.
- Explain in detail how the slow work and the await points interact.

This is far from complete, but at least takes another reasonable step
toward an explanation, while keeping the level of detail relatively
manageable, I think.

This makes compiled output in listings much more reasonable. It may be
worth seeing if we can trim it down even further. (Switching to `smol`
would do that, I think, but would have other effects.)

Explain how it relates to `futures::future::select` and why `trpl` uses
`race` semantics instead.