[WIP] async and .await chapter
#3909
Conversation
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.
There was a problem hiding this comment.
Some context on these comments: I know this is an early draft, but I have pointed out some things that appear small but I think are important for us to figure out while working, like figuring out what terminology we should standardize on and where we should define which terms. Please feel free to tell me "yeah yeah I agree but don't want to think about that right now" :)
1,000% on board with this! Also very on board with working on this separate branch. I will likely keep the other around for reference (and we may even be able to merge it when all is said and done, who knows), but it will be a lot easier to deal with the mechanical bits separately from the prose bits, and we really don’t want to land any of that till we are actually ready to land the chapter. 😅 I have replied to most of the comments here, and I have read all of them; if I haven’t yet replied to one it is just because I am still mulling on it! |
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`.
chriskrycho
force-pushed
the
only-new-async
branch
2 times, most recently
from
f3fc42f to
87a015f
Compare
chriskrycho
force-pushed
the
only-new-async
branch
from
f6d2e30 to
ddad349
Compare
- Set their view boxes to the original height and width, so they are guaranteed to present correctly. - For Figure 17-02, use the trick of adding a hidden node and hidden arrow to it in “Task 2” to align the two boxes.
- Create a section (which will be deleted or at least reintegrated once all is said and done) to hold content pulled out of other sections for the sake of clearer flow and understanding. - Pull “advanced” material from 17.00, 17.01, and 17.02 into the holding section and start reorganizing their content to account for shifting around materials.
The `block_on` name is what both Tokio and smol use, but it is a bit obscure from the point of view of introducing this material. `run` says much more clearly what it does *for the level we care about here*, I think.
These make up *most* of the rest of the edits I caught while rereading which are not *major structural revisions*, along with some of the bits required for those major structural revisions.
This does *not* yet incorporate any of the relevant feedback from Carol on this, so a couple spots are still pretty messy.
Along with the wording and phrasing-level edits, pull out a fair bit of material for the “advanced” section at the end, specifically the details of what `Stream` and `StreamExt` actually do.
Bonus: fix some style guide issues, too! Co-authored-by: Carol (Nichols || Goulding) <[email protected]> Co-authored-by: James Munns <[email protected]> Co-authored-by: Tim McNamara <[email protected]>
Co-authored-by: James Munns <[email protected]>
Co-authored-by: Tim McNamara <[email protected]> Co-authored-by: Carol (Nichols || Goulding) <[email protected]>
I accidentally copied these in when pulling in the `trpl-note` mdbook preprocessor many months ago, and we did not notice amidst the many other changes in that PR!
Add `reqwest` and `scraper` dependencies to the `trpl` crate. Wrap them in `trpl` re-exports which keep the API surface low. Rewrite the whole first section to use `race` along with those `trpl` re-exports to show a more “real” example of async code right form the start, including actual concurrency, unlike the previous introduction. Update 17.03 to account for having introduced `race` already, and update listing numbers for rewritten 17.01. The *inclues* for them were fixed already, but not these!
This gets CI working again. The problem was basically a mix of a few silly mistakes: - Using `include` instead of `rustdoc_include` in several places. - Having rewritten the listing numbers incorrectly.
|
All right, status: I have made a huge revision to the chapter—most of the content is the same, but the structure is very different, and I completely replaced the example in 17.01 to get “real” async happening up front much sooner. Given that this PR is basically destroying GitHub, I am going to:
🚀 Just want to say here publicly (as I will do in many other places) a huge thanks to @timClicks, @willcrichton, and @jamesmunns as outside reviewers, and of course @carols10cents as co-author, whose input has made this a profoundly better chapter. |
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!)
View the rendered version of this PR at https://rust-lang.github.io/book/ch17-00-async-await.html.
Note
This branch does not include changes to the listings for the chapters after this new chapter. As @carols10cents put it:
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!