[WIP] async and .await chapter with all changes
#3908
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.
|
😬 GitHub is straight up not having a good time rendering the full diff with all the listing changes... so I'm opening a new PR without the listings moving for now 😱 |
|
😂 Good job, GitHub! |
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`.
htypes! What are htypes? No one will ever know. Co-authored-by: James Munns <james@onevariable.com>
mdBook does not currently have particularly good support for “external” crates. To make the test suite work correctly with `trpl`, we must first build `trpl` itself (`mdbook` will not do it), and then explicitly pass its `deps` path as a library search path for `mdbook test`. That will make sure all the crates can be resolved when running the tests. .github/workflows/main.yml
- Update the contents of the code in the chapter so it is correct, and update the text to match. Given this is about `Future`, this may also warrant moving/simplifying that whole chunk of code, too. - Update the listing to use `extern crate` since it does not otherwise work correctly with `mdbook test`. Alas.
- Update all the listings in the chapter to use `extern crate` since `mdbook test` does not understand Rust 2018. Alas. - Ignore two of the listings because they never stop.
- Update all the listings in the chapter to use `extern crate` since `mdbook test` does not understand Rust 2018. Alas. - Fix one listing which had gotten out of sync somewhere along the way. (This also fixes a comment flagged up by a reviewer!)
- Update all the listings in the chapter to use `extern crate` since `mdbook test` does not understand Rust 2018. Alas. - Ignore a listing which has a missing body apurpose.
- Rewrite the `StreamExt` definition to be more correct, and extract it to a standalone “no-listing listing” so we can make sure its definition at least type checks. - Update all the listings in the chapter to use `extern crate` since `mdbook test` does not understand Rust 2018. Alas. - Ignore the listings (inline or otherwise!) which are *intended* not to compile, so mdbook does not try to test them. - Clarify some of the text around the *actual* Tokio definition of the `StreamExt::next` method.
chriskrycho
force-pushed
the
chriskrycho/chapter-async-await
branch
from
650c74f
to
e9762af
Compare
Note: this does *not* include all fixes for the text, only for the links themselves. For the text, we will also need to search for references to chapters 17-20. This catches a few of those along the way, but there are no doubt others.
chriskrycho
force-pushed
the
chriskrycho/chapter-async-await
branch
from
e9762af
to
a25b8db
Compare
chriskrycho
force-pushed
the
chriskrycho/chapter-async-await
branch
2 times, most recently
from
3226441
to
882c3b6
Compare
chriskrycho
changed the title
async and .await chapter with listings updatesasync and .await chapter with all changes
Co-authored-by: Tim McNamara <paperless@timmcnamara.co.nz> Co-authored-by: James Munns <james@onevariable.com>
Co-authored-by: Carol (Nichols || Goulding) <carol.nichols@gmail.com> Co-authored-by: Will Crichton <crichton.will@gmail.com> Co-authored-by: Tim McNamara <paperless@timmcnamara.co.nz>
Use the original transitional paragraph and structure, adding to it instead of rewriting it entirely. HT @timClicks (Tim McNamara <paperless@timmcnamara.co.nz>) for pointing out how my rephrasing here made it worse!
- Drop the history lesson and comparisons to other approaches. Focus on what async gives us instead. - Simplify and clarify the - Talk about “the network” instead of “network sockets” and simplify the example code to match.
- Swap the ordering to match the order in the text (concurrent is first, at least for now). - Make them go left-to-right instead of top-to-bottom for compactness in the text. - Fix rendering issues resulting from the VS Code extension doing things that normal `dot` does not, for who knows what reasons.
chriskrycho
force-pushed
the
chriskrycho/chapter-async-await
branch
from
882c3b6
to
de155fe
Compare
chriskrycho
force-pushed
the
chriskrycho/chapter-async-await
branch
from
de155fe
to
ce40557
Compare
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.
Everything for the new Chapter 17.
Note
Work is actually happening on #3909 and other branches moving into it over time. This PR generally includes everything that #3909 includes, any ongoing edits (e.g. those in #3965, #3983, etc.), and the listings rework—but that last bit means GitHub has a very bad time trying to render the diff. I am maintaining this branch and PR so that I can keep the listings in reasonably good shape as we make changes to
srcas it stands today, so that when we finally go to merge this thing it is not an extra pile of work all at once.