Address latest structural feedback

Author: tall-vase

src/SUMMARY.md

@@ -449,8 +449,8 @@
     - [Generalizing "Ownership"](idiomatic/leveraging-the-type-system/borrow-checker-invariants/generalizing-ownership.md)
     - [Single-use values](idiomatic/leveraging-the-type-system/borrow-checker-invariants/single-use-values.md)
     - [Aliasing XOR Mutability](idiomatic/leveraging-the-type-system/borrow-checker-invariants/aliasing-xor-mutability.md)
-    - [Lifetime Relationships primer: PhantomData](idiomatic/leveraging-the-type-system/borrow-checker-invariants/phantomdata.md)
-    - [Lifetime Relationships & External Resources](idiomatic/leveraging-the-type-system/borrow-checker-invariants/lifetime-connections.md)
+    - [PhantomData and Types](idiomatic/leveraging-the-type-system/borrow-checker-invariants/phantomdata-01-types.md)
+    - [PhantomData and Lifetimes](idiomatic/leveraging-the-type-system/borrow-checker-invariants/phantomdata-02-lifetimes.md)
 
 ---
 

src/idiomatic/leveraging-the-type-system/borrow-checker-invariants.md

@@ -1,11 +1,11 @@
 ---
-minutes: 10
+minutes: 15
 ---
 
 # Using the Borrow checker to enforce Invariants
 
-The borrow checker, while added to enforce memory ownership, can be
-leveraged model other problems and prevent API misuse.
+The borrow checker, while added to enforce memory ownership, can be leveraged
+model other problems and prevent API misuse.
 
 ```rust,editable
 /// Doors can be open or closed, and you need the right key to lock or unlock
@@ -53,26 +53,56 @@ fn main() {
 
 <details>
 
-<!-- TODO: link to typestate when that gets merged. -->
-
 - The borrow checker has been used to prevent use-after-free and multiple
   mutable references up until this point, and we've used types to shape and
   restrict use of APIs already using
   [the Typestate pattern](../leveraging-the-type-system/typestate-pattern.md).
 
-- This example uses the ownership & borrowing rules to model the locking and
-  unlocking of a door. We can try to open a door with a key, but if it's the
-  wrong key the door is still closed (here represented as an error) and the key
-  persists regardless.
+- Language features are often introduced for a specific purpose.
+
+  Over time, users may develop ways of using a feature in ways that were not
+  predicted when they were introduced.
+
+  In 2004, Java 5 introduced Generics with the
+  [main stated purpose of enabling type-safe collections](https://jcp.org/en/jsr/detail?id=14).
+
+  Since then, users and developers of the language expanded the use of generics
+  to other areas of type-safe API design.
+  <!-- TODO: Reference how this was adopted -->
+
+  What we aim to do here is similar: Even though the borrow checker was
+  introduced to prevent use-after-free and data races, it is just another API
+  design tool. It can be used to model program properties that have nothing to
+  do with preventing memory safety bugs.
+
+- To use the borrow checker as a problem solving tool, we will need to "forget"
+  that the original purpose of it is to prevent mutable aliasing in the context
+  of preventing use-after-frees and data races.
+
+  We should imagine working within situations where the rules are the same but
+  the meaning is slightly different.
+
+- This example uses ownership and borrowing are used to model the state of a
+  physical door.
+
+  `open_door` **consumes** a `LockedDoor` and returns a new `OpenDoor`. The old
+  `LockedDoor` value is no longer available.
+
+  If the wrong key is used, the door is left locked. It is returned as an `Err`
+  case of the `Result`.
+
+  It is a compile-time error to try and use a door that has already been opened.
+
+- Similarly, `lock_door` consumes an `OpenDoor`, preventing closing the door
+  twice at compile time.
+
+- The rules of the borrow checker exist to prevent memory safety bugs, but the
+  underlying logical system does not "know" what memory is.
 
-- The rules of the borrow checker exist to prevent memory safety bugs. However, the underlying
-  logical system does not "know" what memory is. All it does is enforce a
-  specific set of rules of how different operations affect what later operations
-  are possible.
+  All the borrow checker does is enforce a specific set of rules of how users
+  can order operations.
 
-- Those rules can apply to many other cases: We can piggy-back onto the rules of
-  the borrow checker to design APIs to be harder or impossible to misuse, even
-  when there's little or no "memory safety" concerns in the problem domain. This
-  section will walk through some of those different domains.
+  This is just one case of piggy-backing onto the rules of the borrow checker to
+  design APIs to be harder or impossible to misuse.
 
 </details>

src/idiomatic/leveraging-the-type-system/borrow-checker-invariants/aliasing-xor-mutability.md

@@ -2,98 +2,112 @@
 minutes: 15
 ---
 
-# Mutually Exclusive References, or "Aliasing XOR Mutability"
+# Mutually Exclusive References / "Aliasing XOR Mutability"
 
 We can use the mutual exclusion of `&T` and `&mut T` references for a single
 value to model some constraints.
 
-```rust,editable,compile_fail
-pub struct Transaction(/* specifics omitted */);
-pub struct QueryResult(String);
-
-pub struct DatabaseConnection {
-    transaction: Transaction,
-    query_results: Vec<QueryResult>,
-}
+```rust,editable
+pub struct QueryResult;
+pub struct DatabaseConnection {/* fields omitted */}
 
 impl DatabaseConnection {
     pub fn new() -> Self {
-        Self {
-            transaction: Transaction(/* again, specifics omitted */),
-            query_results: vec![],
-        }
-    }
-    pub fn get_transaction(&mut self) -> &mut Transaction {
-        &mut self.transaction
+        Self {}
     }
     pub fn results(&self) -> &[QueryResult] {
-        &self.query_results
-    }
-    pub fn commit(&mut self) {
-        // Work omitted, including sending/clearing the transaction
-        println!("Transaction committed!")
+        &[] // fake results
     }
 }
 
-pub fn do_something_with_transaction(transaction: &mut Transaction) {}
+pub struct Transaction<'a> {
+    connection: &'a mut DatabaseConnection,
+}
+
+impl<'a> Transaction<'a> {
+    pub fn new(connection: &'a mut DatabaseConnection) -> Self {
+        Self { connection }
+    }
+    pub fn query(&mut self, _query: &str) {
+        // Send the query over, but don't wait for results.
+    }
+    pub fn commit(self) {
+        // Finish executing the transaction and retrieve the results.
+    }
+}
 
 fn main() {
     let mut db = DatabaseConnection::new();
-    let mut transaction = db.get_transaction();
-    do_something_with_transaction(transaction);
-    let assumed_the_transactions_happened_immediately = db.results(); // ❌🔨
-    do_something_with_transaction(transaction);
-    // Works, as the lifetime of "transaction" as a reference ended above.
-    let assumed_the_transactions_happened_immediately_again = db.results();
-    db.commit();
+
+    // The transaction `tx` mutably borrows `db`.
+    let mut tx = Transaction::new(&mut db);
+    tx.query("SELECT * FROM users");
+
+    // This won't compile because `db` is already mutably borrowed.
+    // let results = db.results(); // ❌🔨
+
+    // The borrow of `db` ends when `tx` is consumed by `commit`.
+    tx.commit();
+
+    // Now it is possible to borrow `db` again.
+    let results = db.results();
 }
 ```
 
 <details>
 
-- Aliasing XOR Mutability means "we can have multiple immutable references, a
-  single mutable reference, but not both."
+- Motivation: When working with a database API, a user might imagine that
+  transactions are being committed "as they go" and try to read results in
+  between queries being added to the transaction. This fundamental misuse of the
+  API could lead to confusion as to why nothing is happening.
+
+  While an obvious misunderstanding, situations such as this can happen in
+  practice.
 
-- This example shows how we can use the mutual exclusion of these kinds of
-  references to dissuade a user from reading query results while using a
-  transaction API.
+  Ask: Has anyone misunderstood an API by not reading the docs for proper use?
+
+  Expect: Examples of early-career or in-university mistakes and
+  misunderstandings.
+
+  As an API grows in size and user base, a smaller percentage may have "total"
+  knowledge of the system the API represents.
+
+- This example shows how we can use Aliasing XOR Mutability prevent this kind of
+  misuse
 
   This might happen if the user is working under the false assumption that the
   queries being written to the transaction happen "immediately" rather than
   being queued up and performed together.
 
-- By borrowing one field of a struct via a method that returns a mutable /
-  exclusive reference we prevent access to the other fields of that struct under
-  a shared / non-exclusive reference until the lifetime of that borrow ends.
-
-- The `transaction` field must be borrowed via a method, as the compiler can
-  reason about borrowing different fields in mutable/shared ways simultaneously
-  if that borrowing is done manually.
+- The constructor for the Transaction type takes a mutable reference to the
+  database connection, which it holds onto that reference.
 
-  Demonstrate:
+  The explicit lifetime here doesn't have to be intimidating, it just means
+  "`Transaction` is outlived by the `DatabaseConnection` that was passed to it"
+  in this case.
 
-  - Change the instances of `db.get_transaction()` and `db.results()` to manual
-    borrows (`&mut db.transaction` and `&db.query_results` respectively) to show
-    the difference in what the borrow checker allows.
+  The `mut` keyword in the type lets us determine that there is just one of
+  these references present per variable of type `DatabaseConnection`.
 
-  - Put the non-`main` part of this example in a module to reiterate that this
-    manual access is not possible across module boundaries.
+- While a `Transaction` exists, we can't touch the `DatabaseConnection` variable
+  that was created from it.
 
-- As laid out in [generalizing ownership](generalizing-ownership.md) we can look
-  at the ways Mutable References and Shareable References interact to see if
-  they fit with the invariants we want to uphold for an API.
+  Demonstrate: uncomment the `db.results()` line.
 
-- In this case, having the query results not public and placed behind a getter
-  function, we can enforce the invariant "users of this API are not looking at
-  the query results at the same time as they are writing to a transaction."
+- This lifetime parameter for `Transaction` needs to come from somewhere, in
+  this case it is derived from the lifetime of the owned `DatabaseConnection`
+  from which an exclusive reference is being passed.
 
-- The "don't look at query results while building a transaction" invariant can
-  still be circumvented, how so?
+- As laid out in [generalizing ownership](generalizing-ownership.md) and
+  [the opening slide for this section](../borrow-checker-invariants.md) we can
+  look at the ways Mutable References and Shareable References interact to see
+  if they fit with the invariants we want to uphold for an API.
 
-  - The user could access the transaction solely through `db.get_transaction()`,
-    leaving the lifetime too temporary to prevent access to `db.results()`.
+- Note: The query results not being public and placed behind a getter function
+  lets us enforce the invariant "users can only look at query results if they
+  are not also writing to a transaction."
 
-  - How could we avoid this by working in other concepts from "Leveraging the
-    Type System"?
+  If they're publicly available to the user outside of the definition module
+  then this invariant can be invalidated.
 
 </details>

src/idiomatic/leveraging-the-type-system/borrow-checker-invariants/generalizing-ownership.md

@@ -1,14 +1,14 @@
 ---
-minutes: 15
+minutes: 5
 ---
 
-# Generalizing Ownership
+# Generalizing Ownership: Lifetimes Refresher
 
 The logic of the borrow checker, while modelled off "memory ownership", can be
 abstracted away from that use case to model other problems where we want to
 prevent API misuse.
 
-```rust,editable,compile_fail
+```rust,editable
 // An internal data type to have something to hold onto.
 pub struct Internal;
 // The "outer" data.
@@ -24,11 +24,11 @@ fn deny_future_use(value: Data) {}
 
 fn main() {
     let mut value = Data(Internal);
-    let deny_mut = shared_use(&value);
-    let try_to_deny_immutable = exclusive_use(&mut value); // ❌🔨
-    let more_mut_denial = &deny_mut;
+    let shared = shared_use(&value);
+    // let exclusive = exclusive_use(&mut value); // ❌🔨
+    let shared_again = &shared;
     deny_future_use(value);
-    let even_more_mut_denial = shared_use(&value); // ❌🔨
+    // let shared_again_again = shared_use(&value); // ❌🔨
 }
 ```
 
@@ -38,51 +38,31 @@ fn main() {
   towards semantic meaning in non-memory-safety settings. Nothing is being
   mutated, nothing is being sent across threads.
 
-- Language features are often introduced for a specific purpose.
-
-  Over time, users may develop ways of using that feature in ways that may have
-  not been foreseen.
-
-  In 2004, Java 5 introduced Generics with the
-  [main stated purpose of enabling type-safe collections](https://jcp.org/en/jsr/detail?id=14).
-
-  Since then, users and developers of the language expanded the use of generics
-  to other areas of type-safe API design.
-  <!-- TODO: Reference how this was adopted -->
+- In rust's borrow checker we have access to three different ways of "taking" a
+  value:
 
-  What we aim to do here is similar: Even though the borrow checker was
-  introduced to prevent use-after-free and data races, it is just another API
-  design tool. It can be used to model program properties that have nothing to
-  do with preventing memory safety bugs.
+  - Owned value `T`. Value is dropped when the scope ends, unless it is not
+    returned to another scope.
 
-- To use the borrow checker as a problem solving tool, we will need to "forget"
-  that the original purpose of it is to prevent mutable aliasing in the context
-  of preventing use-after-frees and data races, instead imagining and working
-  within situations where the rules are the same but the meaning is slightly
-  different.
+  - Shared Reference `&T`. Allows aliasing but prevents mutable access while
+    shared references are in use.
 
-- In rust's borrow checker we have access to three different ways of "taking" a
-  value:
+  - Mutable Reference `&mut T`. Only one of these is allowed to exist for a
+    value at any one point, but can be used to create shared references.
 
-  <!-- TODO: actually link to the RAII section when it has been merged. -->
-  - Owned value `T`. Very permissive case, to the point where mutability can be
-    re-set, but demands that nothing else is using it in any context and drops
-    the value when scope ends (unless that scope returns this value) (see:
-    RAII.)
+- Ask: The two commented-out lines in `main` would cause compilation errors,
+  Why?
 
-  - Mutable Reference `&mut T`. While holding onto a mutable reference we can
-    still "dispatch" to methods and functions that take an immutable, shared
-    reference of the value but only as long as we're not aliasing immutable,
-    shared references to related data "after" that dispatch.
+  1: Because the `shared` value is still aliased after the `exclusive` reference
+  is taken.
 
-  - Shared Reference `&T`. Allows aliasing but prevents mutable access while any
-    of these exist. We can't "dispatch" to methods and functions that take
-    mutable references when all we have is a shared reference.
+  2: Because `value` is consumed (AKA dropped) the line before the
+  `shared_again_again` reference is taken from `&value`.
 
 - Remember that every `&T` and `&mut T` has a lifetime, just one the user
   doesn't have to annotate or think about most of the time. We get to avoid
   annotating a lot of lifetimes because the rust compiler allows a user to elide
   the majority of them. See:
-  [Lifetime Elision](../../../lifetimes/lifetime-elision.md).
+  [Lifetime Elision](../../../lifetimes/lifetime-elision.md)
 
 </details>