Chapter 17: Async and Await #4037
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
- 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.
Per the [async working group][wg], the _status quo_ for this is unlikely to change before we go to print. We can of course update the online copy as soon as it *does* change, and if it happens to change such that we can sneak it in before going to press, great. [wg]: https://rust-lang.zulipchat.com/#narrow/stream/187312-wg-async/topic/Rename.20AsyncIterator.20back.20to.20Stream.2C.20introduce.20an.20AFIT-based/near/475300446
chriskrycho
force-pushed
the
async-chapter
branch
from
78881f6
to
8f63245
Compare
This gives people a better chance of understanding how the pieces fit together.
These made more sense when this section was all about big ideas and the runtimes; now it’s needless since we actually spent the section building something non-trivial.
- One example compiles that I used to think didn’t. Probably the result of some renumbering. Need to check *all* of those. - Don’t repeat the same basic “you <verb>” form so much.
- Fix the numbers on the SVG files so they match up again after having added a new 17-3 earlier in the chapter. - Actually explain what `Context` is *for*, even though we don’t get into the details of using it.
So many “however” sections! Etc.
chriskrycho
force-pushed
the
async-chapter
branch
from
16d002d
to
887694b
Compare
Incorporate chapter numbering changes for new Ch. 17
chriskrycho
changed the title
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
A working draft of a new chapter on async and await! If you have been invited to give comments, please do so! If you’re not someone we have actively invited, we kindly ask you to hold off: although we are working in public, we cannot absorb too much feedback at once. Thanks!
Status: this has been through multiple revisions, including integrating feedback from the first several rounds of review, and is very nearly ready to publish. 🎉 🚀 It still has a few small items to tackle before we can merge it and ship the chapter to the general public:
Note
This branch does not include changes to the listings for the chapters after this new chapter.
Additionally, we will need to make some other small changes to other chapters (and possibly some significant ones to the “final project” chapter) to account for having this new material in place. Those are all also out of scope for this PR!
This PR replaces and supersedes #3909. It intentionally does not yet include the changes from #3908, which will need to be recreated on top of this, likely as a series of separate pull requests to make the reviews possible.