rust-lang · carols10cents · Apr 24, 2024 · Apr 24, 2024 · Apr 24, 2024 · Apr 24, 2024
diff --git a/.github/workflows/main.yml b/.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

diff --git a/2018-edition/src/ch17-03-oo-design-patterns.md b/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).
diff --git a/Cargo.toml b/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,

diff --git a/ci/dictionary.txt b/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,6 +147,7 @@ DisplayBacktrace
 DivAssign
 DraftPost
 DSTs
+durations
 ebook
 ebooks
 Edsger
@@ -179,6 +182,7 @@ filesystem's
 filesystems
 filmmaking
 Firefox
+FirstAwaitPoint
 FnMut
 FnOnce
 formatter
@@ -197,6 +201,7 @@ grapheme
 Grapheme
 growable
 gzip
+handoff
 hardcode
 hardcoded
 hardcoding
@@ -241,6 +246,7 @@ inline
 instantiation
 internet
 interoperate
+IntoFuture
 IntoIterator
 InvalidDigit
 invariants
@@ -256,6 +262,7 @@ isize
 iter
 iterator's
 JavaScript
+JoinAll
 JoinHandle
 Kay's
 kinded
@@ -294,6 +301,8 @@ Metadata
 metaprogramming
 mibbit
 Mibbit
+microcontroller
+microcontrollers
 millis
 minigrep
 mixup
@@ -307,17 +316,20 @@ monomorphized
 MoveMessage
 Mozilla
 mpsc
+MSRV
 msvc
 MulAssign
 multibyte
 multithreaded
+multithreading
 mutex
 mutex's
 Mutex
 mutexes
 Mutexes
 MutexGuard
 mutext
+MyAsyncStateMachine
 MyBox
 myprogram
 namespace
@@ -359,6 +371,7 @@ OutlinePrint
 overloadable
 overread
 PanicPayload
+parallelizable
 param
 parameterize
 ParseIntError
@@ -371,6 +384,7 @@ PlaceholderType
 polymorphism
 PoolCreationError
 portia
+postfix
 powershell
 PowerShell
 powi
@@ -396,6 +410,8 @@ RangeTo
 RangeFull
 README
 READMEs
+ReadFinished
+ReceiverStream
 rect
 recurse
 recv
@@ -438,6 +454,7 @@ sampleproject
 screenshot
 searchstring
 SecondaryColor
+SecondAwaitPoint
 SelectBox
 semver
 SemVer
@@ -455,6 +472,7 @@ SliceIndex
 Smalltalk
 snuck
 someproject
+SomeType
 someusername
 SPDX
 spdx
@@ -470,6 +488,7 @@ stdlib
 stdout
 steveklabnik's
 stringify
+StreamExt
 Stroustrup
 Stroustrup's
 struct
@@ -514,6 +533,8 @@ tlborm
 tlsv
 TODO
 TokenStream
+Tokio
+tokio
 toml
 TOML
 toolchain
@@ -538,6 +559,7 @@ uncomment
 Uncomment
 uncommenting
 unevaluated
+unhandled
 Uninstalling
 uninstall
 unittests
@@ -556,6 +578,7 @@ username
 USERPROFILE
 usize
 UsState
+util
 utils
 vals
 variable's

diff --git a/dot/trpl17-01.dot b/dot/trpl17-01.dot
@@ -0,0 +1,44 @@
+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";
+
+      // for horizontal alignment purposes only
+      // newrank = true;
+
+      B0 [style = invis;];
+
+      B1;
+      B2;
+      B3;
+
+      B0 -> B1 -> B2 -> B3 [style = invis;];
+   }
+
+   A1 -> B1 -> A2 -> B2 -> A3 -> A4 -> B3;
+}
diff --git a/dot/trpl17-02.dot b/dot/trpl17-02.dot
@@ -0,0 +1,20 @@
+digraph {
+   dpi = 300.0;
+
+   rankdir = "LR";
+   splines = false;
+   cluster = true;
+
+   node [shape = diamond;];
+
+   subgraph cluster_ColleagueA {
+      newrank = true;
+      label = "Task 1";
+      A1 -> A2 -> A3 -> A4;
+   }
+
+   subgraph cluster_ColleagueB {
+      label = "Task 2";
+      B1 -> B2 -> B3;
+   }
+}
diff --git a/listings/ch17-async-await/listing-17-01/Cargo.lock b/listings/ch17-async-await/listing-17-01/Cargo.lock
diff --git a/listings/ch17-async-await/listing-17-01/Cargo.toml b/listings/ch17-async-await/listing-17-01/Cargo.toml
@@ -0,0 +1,6 @@
+[package]
+name = "async_await"
+version = "0.1.0"
+edition = "2021"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
diff --git a/listings/ch17-async-await/listing-17-01/output.txt b/listings/ch17-async-await/listing-17-01/output.txt
@@ -0,0 +1,14 @@
+$ cargo run
+   Compiling async_await v0.1.0 (/Users/chris/dev/rust-lang/book/listings/ch17-async-await/listing-17-01)
+warning: unused implementer of `Future` that must be used
+ --> src/main.rs:3:5
+  |
+3 |     hello("async");
+  |     ^^^^^^^^^^^^^^
+  |
+  = note: futures do nothing unless you `.await` or poll them
+  = note: `#[warn(unused_must_use)]` on by default
+
+warning: `async_await` (bin "async_await") generated 1 warning
+    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.21s
+     Running `target/debug/async_await`
diff --git a/listings/ch17-async-await/listing-17-01/src/main.rs b/listings/ch17-async-await/listing-17-01/src/main.rs
@@ -0,0 +1,10 @@
+// ANCHOR: all
+fn main() {
+    hello("async");
+}
+
+async fn hello(name: &str) {
+    let greeting = format!("Hello, {name}!");
+    println!("{greeting}");
+}
+// ANCHOR_END: all
diff --git a/listings/ch17-async-await/listing-17-02/Cargo.lock b/listings/ch17-async-await/listing-17-02/Cargo.lock
diff --git a/listings/ch17-async-await/listing-17-02/Cargo.toml b/listings/ch17-async-await/listing-17-02/Cargo.toml
@@ -0,0 +1,6 @@
+[package]
+name = "async_await"
+version = "0.1.0"
+edition = "2021"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
diff --git a/listings/ch17-async-await/listing-17-02/output.txt b/listings/ch17-async-await/listing-17-02/output.txt
@@ -0,0 +1,12 @@
+$ cargo run
+   Compiling async_await v0.1.0 (/Users/chris/dev/rust-lang/book/listings/ch17-async-await/listing-17-02)
+error[E0728]: `await` is only allowed inside `async` functions and blocks
+ --> src/main.rs:3:20
+  |
+2 | fn main() {
+  |    ---- this is not `async`
+3 |     hello("async").await;
+  |                    ^^^^^ only allowed inside `async` functions and blocks
+
+For more information about this error, try `rustc --explain E0728`.
+error: could not compile `async_await` (bin "async_await") due to 1 previous error
diff --git a/listings/ch17-async-await/listing-17-02/src/main.rs b/listings/ch17-async-await/listing-17-02/src/main.rs
@@ -0,0 +1,10 @@
+// ANCHOR: main
+fn main() {
+    hello("async").await;
+}
+// ANCHOR_END: main
+
+async fn hello(name: &str) {
+    let greeting = format!("Hello, {name}!");
+    println!("{greeting}");
+}
diff --git a/listings/ch17-async-await/listing-17-03/Cargo.lock b/listings/ch17-async-await/listing-17-03/Cargo.lock
diff --git a/listings/ch17-async-await/listing-17-03/Cargo.toml b/listings/ch17-async-await/listing-17-03/Cargo.toml
@@ -0,0 +1,6 @@
+[package]
+name = "async_await"
+version = "0.1.0"
+edition = "2021"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
diff --git a/listings/ch17-async-await/listing-17-03/output.txt b/listings/ch17-async-await/listing-17-03/output.txt
@@ -0,0 +1,10 @@
+$ cargo run
+   Compiling async_await v0.1.0 (/Users/chris/dev/rust-lang/book/listings/ch17-async-await/listing-17-03-fix)
+error[E0752]: `main` function is not allowed to be `async`
+ --> src/main.rs:2:1
+  |
+2 | async fn main() {
+  | ^^^^^^^^^^^^^^^ `main` function is not allowed to be `async`
+
+For more information about this error, try `rustc --explain E0752`.
+error: could not compile `async_await` (bin "async_await") due to 1 previous error
diff --git a/listings/ch17-async-await/listing-17-03/src/main.rs b/listings/ch17-async-await/listing-17-03/src/main.rs
@@ -0,0 +1,10 @@
+// ANCHOR: main
+async fn main() {
+    hello("async").await;
+}
+// ANCHOR_END: main
+
+async fn hello(name: &str) {
+    let greeting = format!("Hello, {name}!");
+    println!("{greeting}");
+}