[WIP] async and .await chapter
#3909
Draft
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
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.
carols10cents
commented
Apr 30, 2024
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
This pushes back the Tasks, Futures, and Threads discussion one more spot, to become §06.
chriskrycho
force-pushed
the
only-new-async
branch
from
bfdbe71
to
74df84e
Compare
This is actually the first time it appears in the book, to my great surprise! We will also need to update Chapter 19 to account for having introduced this form already, following the example for how it handles Chapter 6’s introduction of `if let`.
I moved this into dedicated listings appropriately but forgot to remove the original.
chriskrycho
force-pushed
the
only-new-async
branch
2 times, most recently
from
9b5a2cb
to
11243bf
Compare
Also start laying the foundation for (a) showing how that interacts with previous material, e.g. around slow operations; and (b) showing how it composes nicely with other async operations, e.g. timeouts, throttling, and (maybe!) even merging streams.
chriskrycho
force-pushed
the
only-new-async
branch
4 times, most recently
from
797d64e
to
735399a
Compare
Use `IntervalStream` and `ReceiverStream` to show the composition of multiple streams, along with throttling and timeouts. This will also provide a useful foundation for discussing the relationships between futures, tasks, and threads in the final sections of the book, since you can accomplish the same basic API by simply substituting threads for tasks—but with different tradeoffs!
chriskrycho
force-pushed
the
only-new-async
branch
from
735399a
to
3c6c32c
Compare
- Reintroduce accidentally-dropped content. I meant to simply carry this over in 74df84e, but failed to, perhaps because I had `mdbook serve` running and it tries to be helpful about generating files which are referenced in `SUMMARY.md` but do not exist on disk. Either way, this is back now and we can use it to explain these concepts. - Start on an example showing how `thread::spawn` and `spawn_task` are basically interchangeable from an API POV, so that we can then see how they differ in terms of runtime consequences.
- Added a discussion of the relationship between futures, tasks, and threads—I am not in love with it, but it is a starting point. - Moved the still-to-be-rewritten 'Parallelism and Concurrency' back to §01, where it can be rewritten after getting some feedback.
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.
😬 GitHub is straight up not having a good time rendering the full diff of #3908 with all the listing changes... so I'm opening a new PR without the listings moving for now 😱
Edit by @chriskrycho to add: A quick note for folks watching the repo: the state of this is roughly: Ready for @carols10cents to leave comments, and we’ll invite others to do so as well over time, but please don’t comment-bomb us at this phase! 😂
If you have been invited to give comments, please do so!
View the rendered version of this PR at https://rust-lang.github.io/book/ch17-00-async-await.html.