add 2 extra slides

this completes the raii chapter

Author: GlenDC

src/SUMMARY.md

@@ -446,7 +446,9 @@
     - [Drop Guards](idiomatic/leveraging-the-type-system/raii/drop_guards.md)
     - [Drop Bomb](idiomatic/leveraging-the-type-system/raii/drop_bomb.md)
     - [Drop Skipped](idiomatic/leveraging-the-type-system/raii/drop_skipped.md)
+    - [Drop Bomb Forget](idiomatic/leveraging-the-type-system/raii/drop_bomb_forget.md)
     - [Scope Guard](idiomatic/leveraging-the-type-system/raii/scope_guard.md)
+    - [Drop Option](idiomatic/leveraging-the-type-system/raii/drop_option.md)
   - [Extension Traits](idiomatic/leveraging-the-type-system/extension-traits.md)
     - [Extending Foreign Types](idiomatic/leveraging-the-type-system/extension-traits/extending-foreign-types.md)
     - [Method Resolution Conflicts](idiomatic/leveraging-the-type-system/extension-traits/method-resolution-conflicts.md)

src/idiomatic/leveraging-the-type-system/raii/drop_bomb.md

@@ -14,12 +14,6 @@ struct Transaction {
 }
 
 impl Transaction {
-    /// Begin a [`Transaction`].
-    ///
-    /// ## Panics
-    ///
-    /// Panics if the transaction is dropped without
-    /// calling [`Self::commit`] or [`Self::rollback`].
     fn start() -> Self {
         Self { active: true }
     }
@@ -34,7 +28,7 @@ impl Transaction {
 impl Drop for Transaction {
     fn drop(&mut self) {
         if self.active {
-            panic!("Transaction dropped without commit or rollback!");
+            panic!("Transaction dropped without commit!");
         }
     }
 }
@@ -44,6 +38,7 @@ fn main() -> io::Result<()> {
     // Use `tx` to build the transaction, then commit it.
     // Comment out the call to `commit` to see the panic.
     tx.commit()?;
+    Ok(())
 }
 ```
 

src/idiomatic/leveraging-the-type-system/raii/drop_bomb_forget.md

@@ -0,0 +1,49 @@
+# Drop Bombs: using `std::mem::forget`
+
+```rust,editable
+use std::io::{self, Write};
+
+struct Transaction;
+
+impl Transaction {
+    fn start() -> Self {
+        Transaction
+    }
+
+    fn commit(self) -> io::Result<()> {
+        writeln!(io::stdout(), "COMMIT")?;
+
+        // Defuse the drop bomb by preventing Drop from ever running.
+        std::mem::forget(self);
+
+        Ok(())
+    }
+}
+
+impl Drop for Transaction {
+    fn drop(&mut self) {
+        // This is the "drop bomb"
+        panic!("Transaction dropped without commit!");
+    }
+}
+
+fn main() -> io::Result<()> {
+    let tx = Transaction::start();
+    // Use `tx` to build the transaction, then commit it.
+    // Comment out the call to `commit` to see the panic.
+    tx.commit()?;
+    Ok(())
+}
+```
+
+<details>
+
+In the previous slide we saw that calling
+[`std::mem::forget`](https://doc.rust-lang.org/std/mem/fn.forget.html) prevents
+`Drop::drop` from ever running.
+
+This lets us avoid using a runtime flag entirely: when the transaction is
+successfully committed, we can defuse the drop bomb by forgetting the value
+instead of letting its destructor run.
+
+</details>

src/idiomatic/leveraging-the-type-system/raii/drop_option.md

@@ -0,0 +1,84 @@
+# Drop: Option
+
+```rust,editable
+struct File(Option<Handle>);
+
+impl File {
+    fn open(path: &'static str) -> std::io::Result<Self> {
+        Ok(Self(Some(Handle { path })))
+    }
+
+    fn write(&mut self, data: &str) -> std::io::Result<()> {
+        match &mut self.0 {
+            Some(handle) => println!("write '{data}' to file '{}'", handle.path),
+            None => unreachable!(),
+        }
+        Ok(())
+    }
+
+    fn close(mut self) -> std::io::Result<&'static str> {
+        Ok(self.0.take().unwrap().path)
+    }
+}
+
+impl Drop for File {
+    fn drop(&mut self) {
+        if let Some(handle) = self.0.take() {
+            println!("automatically close handle for file: {}", handle.path);
+        }
+    }
+}
+
+struct Handle {
+    path: &'static str,
+}
+impl Drop for Handle {
+    fn drop(&mut self) {
+        println!("close handle for file: {}", self.path)
+    }
+}
+
+fn main() -> std::io::Result<()> {
+    let mut file = File::open("foo.txt")?;
+    file.write("hello")?;
+    println!("manually closed file: {}", file.close()?);
+    Ok(())
+}
+```
+
+<details>
+
+- In this example we want to let the user call `close()` manually so that errors
+  from closing the file can be reported explicitly.
+
+- At the same time we still want RAII semantics: if the user forgets to call
+  `close()`, the handle must be cleaned up automatically in `Drop`.
+
+- Wrapping the handle in an `Option` gives us both behaviors.\
+  `close()` extracts the handle with `take()`, and `Drop` only runs cleanup if a
+  handle is still present.
+  
+  You can demonstrate this by removing the line where we call `.close()`.
+
+- The main downside is ergonomics. `Option` forces us to handle both the `Some`
+  and `None` case even in places where, logically, `None` should be impossible.
+  Rust’s type system cannot express that guarantee here, so we pay a small
+  boilerplate cost.
+
+## More to explore
+
+Instead of `Option` we could use
+[`ManuallyDrop`](https://doc.rust-lang.org/std/mem/struct.ManuallyDrop.html),
+which suppresses automatic destruction and gives full manual control.\
+This approach requires `unsafe`, since `ManuallyDrop` provides no guarantees
+that the programmer uses it correctly.
+
+The [_scopeguard_ example](./scope_guard.md) on the previous slide shows how
+`ManuallyDrop` can replace `Option` to avoid handling `None` in places where the
+value should always exist.
+
+In such designs we typically track the drop state with a separate flag next to
+the `ManuallyDrop<Handle>`, allowing us to express whether the handle has
+already been manually consumed.
+
+</details>

src/idiomatic/leveraging-the-type-system/raii/drop_skipped.md

@@ -69,6 +69,4 @@ fn main() {
 - Finally, consider what happens when you also uncomment the `panic!` inside
   `Foo::drop`.
 
-  TODO...
-
 </details>

src/idiomatic/leveraging-the-type-system/raii/scope_guard.md

@@ -3,7 +3,7 @@
 A scope guard uses the `Drop` trait to ensure cleanup code runs automatically
 when a scope exits — even if due to an error.
 
-```rust,editable,compile_fail
+```rust,editable
 use scopeguard::{ScopeGuard, guard};
 use std::fs::{self, File};
 use std::io::Write;
@@ -27,8 +27,8 @@ fn main() {
 
     if download_successful() {
         // Download succeeded, keep the file
-        let _path = ScopeGuard::into_inner(cleanup);
-        println!("Download complete!");
+        let path = ScopeGuard::into_inner(cleanup);
+        println!("Download '{path}' complete!");
     }
     // Otherwise, the guard runs and deletes the file
 }