Chapter 17: Async and Await

.github/workflows/main.yml

@@ -24,8 +24,19 @@ jobs:
         rustup --version
         rustc -Vv
         mdbook --version
+
+    # 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.
+    - name: Build `trpl` crate
+      run: |
+        cd packages/trpl
+        cargo build
     - name: Run tests
-      run: mdbook test
+      run:
+        mdbook test --library-path packages/trpl/target/debug/deps
   package_tests:
     name: Run package tests
     runs-on: ubuntu-latest

2018-edition/src/ch17-03-oo-design-patterns.md

@@ -3,8 +3,8 @@
 The 2018 edition of the book is no longer distributed with Rust's documentation.
 
 If you came here via a link or web search, you may want to check out [the current
-version of the book](../ch17-03-oo-design-patterns.html) instead.
+version of the book](../ch18-03-oo-design-patterns.html) instead.
 
 If you have an internet connection, you can [find a copy distributed with
 Rust
-1.30](https://doc.rust-lang.org/1.30.0/book/2018-edition/ch17-03-oo-design-patterns.html).
+1.30](https://doc.rust-lang.org/1.30.0/book/2018-edition/ch17-03-oo-design-patterns.html).

Cargo.toml

@@ -6,6 +6,7 @@ exclude = [
     "linkchecker", # linkchecker is part of the CI workflow
     "listings",    # these are intentionally distinct from the workspace
     "tmp",         # listings are built here when updating output via tools/update-rustc.sh
+    "packages/trpl",        # manages its own dependencies as a standalone crate
 
     # These are used as path dependencies in `rust-lang/rust` (since we are not
     # publishing them to crates.io), so they cannot be part of this workspace,

README.md

@@ -73,7 +73,8 @@ $ start chrome.exe .\book\index.html            # Windows (Cmd)
 To run the tests:
 
 ```bash
-$ mdbook test
+$ cd packages/trpl
+$ mdbook test --library-path packages/trpl/target/debug/deps
 ```
 
 ## Contributing

ci/dictionary.txt

@@ -55,6 +55,7 @@ bool
 boolean
 Boolean
 Booleans
+booleans
 Bors
 BorrowMutError
 BoxMeUp
@@ -109,6 +110,7 @@ deallocate
 deallocated
 deallocating
 deallocation
+debounce
 debuginfo
 decl
 decrementing
@@ -145,10 +147,12 @@ DisplayBacktrace
 DivAssign
 DraftPost
 DSTs
+durations
 ebook
 ebooks
 Edsger
 egular
+ElementRef
 else's
 emoji
 encodings
@@ -179,6 +183,7 @@ filesystem's
 filesystems
 filmmaking
 Firefox
+FirstAwaitPoint
 FnMut
 FnOnce
 formatter
@@ -187,6 +192,8 @@ FrenchToast
 FromIterator
 FromResidual
 frontend
+FuturesUnordered
+GetAwaitPoint
 getrandom
 getter
 getters
@@ -197,6 +204,7 @@ grapheme
 Grapheme
 growable
 gzip
+handoff
 hardcode
 hardcoded
 hardcoding
@@ -241,7 +249,9 @@ inline
 instantiation
 internet
 interoperate
+IntoFuture
 IntoIterator
+intra
 InvalidDigit
 invariants
 ioerror
@@ -256,6 +266,7 @@ isize
 iter
 iterator's
 JavaScript
+JoinAll
 JoinHandle
 Kay's
 kinded
@@ -288,12 +299,15 @@ lval
 macOS
 Matsakis
 mathematic
+mdbook
 memoization
 metadata
 Metadata
 metaprogramming
 mibbit
 Mibbit
+microcontroller
+microcontrollers
 millis
 minigrep
 mixup
@@ -307,17 +321,20 @@ monomorphized
 MoveMessage
 Mozilla
 mpsc
+MSRV
 msvc
 MulAssign
 multibyte
 multithreaded
+multithreading
 mutex
 mutex's
 Mutex
 mutexes
 Mutexes
 MutexGuard
 mutext
+MyAsyncStateMachine
 MyBox
 myprogram
 namespace
@@ -358,7 +375,9 @@ OurError
 OutlinePrint
 overloadable
 overread
+PageTitleFuture
 PanicPayload
+parallelizable
 param
 parameterize
 ParseIntError
@@ -371,6 +390,7 @@ PlaceholderType
 polymorphism
 PoolCreationError
 portia
+postfix
 powershell
 PowerShell
 powi
@@ -396,6 +416,8 @@ RangeTo
 RangeFull
 README
 READMEs
+ReadFinished
+ReceiverStream
 rect
 recurse
 recv
@@ -438,6 +460,7 @@ sampleproject
 screenshot
 searchstring
 SecondaryColor
+SecondAwaitPoint
 SelectBox
 semver
 SemVer
@@ -455,6 +478,7 @@ SliceIndex
 Smalltalk
 snuck
 someproject
+SomeType
 someusername
 SPDX
 spdx
@@ -470,6 +494,7 @@ stdlib
 stdout
 steveklabnik's
 stringify
+StreamExt
 Stroustrup
 Stroustrup's
 struct
@@ -502,6 +527,7 @@ TcpListener
 TcpStream
 templating
 test's
+TextAwaitPoint
 TextField
 That'd
 there'd
@@ -514,6 +540,8 @@ tlborm
 tlsv
 TODO
 TokenStream
+Tokio
+tokio
 toml
 TOML
 toolchain
@@ -538,6 +566,7 @@ uncomment
 Uncomment
 uncommenting
 unevaluated
+unhandled
 Uninstalling
 uninstall
 unittests
@@ -556,6 +585,7 @@ username
 USERPROFILE
 usize
 UsState
+util
 utils
 vals
 variable's

dot/trpl17-01.dot

@@ -0,0 +1,41 @@
+digraph {
+   dpi = 300.0;
+
+   rankdir = "LR";
+
+   // makes ordering between subgraphs work
+   newrank = true;
+
+   node [shape = diamond;];
+
+   subgraph cluster_task_a {
+      label = "Task A";
+
+      A1;
+      A2;
+      A3;
+      A4;
+
+      A1 -> A2 -> A3 -> A4 -> A0 [style = invis;];
+
+      // for vertical alignment purposes only
+      A0 [style = invis;];
+
+      // Makes the heights line up between the boxes.
+      A4 -> A0 [style = invis;];
+   }
+
+   subgraph cluster_task_b {
+      label = "Task B";
+
+      B0 [style = invis;];
+
+      B1;
+      B2;
+      B3;
+
+      B0 -> B1 -> B2 -> B3 [style = invis;];
+   }
+
+   A1 -> B1 -> A2 -> B2 -> A3 -> A4 -> B3;
+}

dot/trpl17-02.dot

@@ -0,0 +1,25 @@
+digraph {
+   dpi = 300.0;
+
+   rankdir = "LR";
+   splines = false;
+   cluster = true;
+
+   node [shape = diamond;];
+
+   // The graphs end up with the correct order, i.e. Task 1 *above* Task 2, when
+   // this is first.
+   subgraph cluster_ColleagueB {
+      label = "Task 2";
+      B1 -> B2 -> B3;
+
+      B0 [style = invis;];
+      B3 -> B0 [style = invis;]
+   }
+
+   subgraph cluster_ColleagueA {
+      newrank = true;
+      label = "Task 1";
+      A1 -> A2 -> A3 -> A4;
+   }
+}