[WIP] Ch. 17: second round of edits

src/SUMMARY.md

@@ -108,6 +108,7 @@
     - [More Ways of Combining Futures](ch17-04-more-ways-of-combining-futures.md)
     - [Streams](ch17-05-streams.md)
     - [Futures, Tasks, and Threads](ch17-06-futures-tasks-threads.md)
+    - [Restructuring](ch17-07-wip.md)
 
 - [Object Oriented Programming Features of Rust](ch18-00-oop.md)
     - [Characteristics of Object-Oriented Languages](ch18-01-what-is-oo.md)

src/ch17-01-futures-and-syntax.md

@@ -190,14 +190,25 @@ When we run this, we get the behavior we might have expected initially:
 {{#include ../listings/ch17-async-await/listing-17-04/output.txt}}
 ```
 
-Phew: we finally have some working async code! Now we can turn our attention to
-how the `Future` trait works.
+Phew: we finally have some working async code! Let’s briefly turn our attention
+to how the `Future` trait works.
 
 ### What Are Futures?
 
 A *future* is a data structure which manages the state of some async operation.
-Rust provides the `Future` trait as a building block so different async
-operations can be implemented with different data, but with a common interface.
+It is called a “future” because it represents work which may not be ready now,
+but will become ready at some point in the future. (This same concept shows up
+in many languages, sometimes under other names like “task” or “promise”.) Rust
+provides a `Future` trait as a building block so different async operations can
+be implemented with different data structures, but with a common interface.
+
+Most of the time when writing async Rust, we don’t work directly with the
+`Future` trait. Instead, we use the `async` and `await` keywords we saw above.
+Rust does the work of compiling them into the appropriate calls to the `Future`
+trait, much like it does with `for` loops and the `Iterator` trait. The main
+time you might need to think about the details of the `Future` type are when
+writing your own custom futures.
+
 Here is the definition of the trait:
 
 ```rust

src/ch17-02-concurrency-with-async.md

@@ -228,6 +228,26 @@ long as the condition it relies on is true.
 
 <!-- TODO: update text in ch. 19 to account for our having introduced this. -->
 
+<!--
+  TODO: this might be a thing we can present in simpler form here, and then
+  return to in more detail in a closing section, covering more of a “how the
+  things we have seen work ‘under the hood’” flavor, which digs into the traits
+  and `Pin` and so on. Here, for example:
+
+  > The `rx.recv()` call produces a `Future`, which we await. The runtime will
+  > pause the `Future` until it is ready. Once a message arrives, the future
+  > will resolve to `Some(message)`, as many times as a message arrives. When
+  > the channel closes, regardless of whether *any*  messages have arrived, the
+  > future will instead resolve to `None` to indicate that there are no more
+  > values, and we should stop polling—that is, stop awaiting.
+
+  Then in the final section of the chapter, when describing the mechanics of the
+  `Future` trait, we can say “Recall our description of [this] from [here]. The
+  `recv()` call *by itself* returns a `Future`, and awaiting it polls it, so it
+  gets `Poll::Pending` until it is ready and then `Poll::Ready(Some(message))`
+  or `Poll::Ready(None)`.” etc.
+-->
+
 The `rx.recv()` call produces a `Future`, which we await. While waiting on
 messages to arrive, the future will produce `Poll::Pending`, so the runtime will
 pause it until it is time to check it again. Once a message arrives, `rx.recv()`

src/ch17-07-wip.md

@@ -0,0 +1,9 @@
+> ## Restructuring
+>
+> This is just a placeholder for material that needs to be restructured so that
+> the earlier sections of the book can avoid getting sidetracked into details of
+> things like `Pin` or even just the full gnarliness of the `Future` trait at
+> points where it would be better for the text to keep moving.
+
+---
+