RAII chapter for idiomatic rust (#2820)

This PR adds the RAII chapter for the idiomatic Rust deep dive.

Author: GlenDC

src/SUMMARY.md

@@ -441,6 +441,15 @@
     - [Semantic Confusion](idiomatic/leveraging-the-type-system/newtype-pattern/semantic-confusion.md)
     - [Parse, Don't Validate](idiomatic/leveraging-the-type-system/newtype-pattern/parse-don-t-validate.md)
     - [Is It Encapsulated?](idiomatic/leveraging-the-type-system/newtype-pattern/is-it-encapsulated.md)
+  - [RAII](idiomatic/leveraging-the-type-system/raii.md)
+    - [Drop Skipped](idiomatic/leveraging-the-type-system/raii/drop_skipped.md)
+    - [Mutex](idiomatic/leveraging-the-type-system/raii/mutex.md)
+    - [Drop Guards](idiomatic/leveraging-the-type-system/raii/drop_guards.md)
+    - [Drop Bomb](idiomatic/leveraging-the-type-system/raii/drop_bomb.md)
+    - [Drop Bomb Forget](idiomatic/leveraging-the-type-system/raii/drop_bomb_forget.md)
+    - [forget and drop functions](idiomatic/leveraging-the-type-system/raii/forget_and_drop.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.md

@@ -0,0 +1,94 @@
+---
+minutes: 15
+---
+
+# RAII: `Drop` trait
+
+RAII (**R**esource **A**cquisition **I**s **I**nitialization) ties the lifetime
+of a resource to the lifetime of a value.
+
+[Rust uses RAII to manage memory](https://doc.rust-lang.org/rust-by-example/scope/raii.html),
+and the `Drop` trait allows you to extend this to other resources, such as file
+descriptors or locks.
+
+```rust,editable
+pub struct File(std::os::fd::RawFd);
+
+impl File {
+    pub fn open(path: &str) -> Result<Self, std::io::Error> {
+        // [...]
+        Ok(Self(0))
+    }
+
+    pub fn read_to_end(&mut self) -> Result<Vec<u8>, std::io::Error> {
+        // [...]
+        Ok(b"example".to_vec())
+    }
+
+    pub fn close(self) -> Result<(), std::io::Error> {
+        // [...]
+        Ok(())
+    }
+}
+
+fn main() -> Result<(), std::io::Error> {
+    let mut file = File::open("example.txt")?;
+    println!("content: {:?}", file.read_to_end()?);
+    Ok(())
+}
+```
+
+<details>
+
+- Easy to miss: `file.close()` is never called. Ask the class if they noticed.
+
+- To release the file descriptor correctly, `file.close()` must be called after
+  the last use — and also in early-return paths in case of errors.
+
+- Instead of relying on the user to call `close()`, we can implement the `Drop`
+  trait to release the resource automatically. This ties cleanup to the lifetime
+  of the `File` value.
+
+  ```rust,compile_fail
+  impl Drop for File {
+      fn drop(&mut self) {
+          // libc::close(...);
+          println!("file descriptor was closed");
+      }
+  }
+  ```
+
+- Note that `Drop::drop()` cannot return a `Result`. Any failures must be
+  handled internally or ignored. In the standard library, errors during FD
+  closure inside `Drop` are silently discarded. See the implementation:
+  <https://doc.rust-lang.org/src/std/os/fd/owned.rs.html#169-196>
+
+- When is `Drop::drop` called?
+
+  Normally, when the `file` variable in `main()` goes out of scope (either on
+  return or due to a panic), `drop()` is called automatically.
+
+  If the file is moved into another function (as is this case with
+  `File::close()`), the value is dropped when that function returns — not in
+  `main`.
+
+  In contrast, C++ runs destructors in the original scope even for moved-from
+  values.
+
+- Demo: insert `panic!("oops")` at the start of `read_to_end()` and run it.
+  `drop()` still runs during unwinding.
+
+### More to Explore
+
+The `Drop` trait has another important limitation: it is not `async`.
+
+This means you cannot `await` inside a destructor, which is often needed when
+cleaning up asynchronous resources like sockets, database connections, or tasks
+that must signal completion to another system.
+
+- Learn more:
+  <https://rust-lang.github.io/async-fundamentals-initiative/roadmap/async_drop.html>
+- There is an experimental `AsyncDrop` trait available on nightly:
+  <https://doc.rust-lang.org/nightly/std/future/trait.AsyncDrop.html>
+
+</details>

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

@@ -0,0 +1,92 @@
+---
+minutes: 15
+---
+
+# Drop Bombs: Enforcing API Correctness
+
+Use `Drop` to enforce invariants and detect incorrect API usage. A "drop bomb"
+panics if a value is dropped without being explicitly finalized.
+
+This pattern is often used when the finalizing operation (like `commit()` or
+`rollback()`) needs to return a `Result`, which cannot be done from `Drop`.
+
+```rust,editable
+use std::io::{self, Write};
+
+struct Transaction {
+    active: bool,
+}
+
+impl Transaction {
+    fn start() -> Self {
+        Self { active: true }
+    }
+
+    fn commit(mut self) -> io::Result<()> {
+        writeln!(io::stdout(), "COMMIT")?;
+        self.active = false;
+        Ok(())
+    }
+}
+
+impl Drop for Transaction {
+    fn drop(&mut self) {
+        if self.active {
+            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 some systems, a value must be finalized by a specific API before it is
+  dropped.
+
+  For example, a `Transaction` might need to be committed or rolled back.
+
+- A drop bomb ensures that a value like `Transaction` cannot be silently dropped
+  in an unfinished state. The destructor panics if the transaction has not been
+  explicitly finalized (for example, with `commit()`).
+
+- The finalizing operation (such as `commit()`) usually takes `self` by value.
+  This ensures that once the transaction is finalized, the original object can
+  no longer be used.
+
+- A common reason to use this pattern is when cleanup cannot be done in `Drop`,
+  either because it is fallible or asynchronous.
+
+- This pattern is appropriate even in public APIs. It can help users catch bugs
+  early when they forget to explicitly finalize a transactional object.
+
+- If cleanup can safely happen in `Drop`, some APIs choose to panic only in
+  debug builds. Whether this is appropriate depends on the guarantees your API
+  must enforce.
+
+- Panicking in release builds is reasonable when silent misuse would cause major
+  correctness or security problems.
+
+- Question: Why do we need an `active` flag inside `Transaction`? Why can't
+  `drop()` panic unconditionally?
+
+  Expected answer: `commit()` takes `self` by value and runs `drop()`, which
+  would panic.
+
+## More to explore
+
+Several related patterns help enforce correct teardown or prevent accidental
+drops.
+
+- The [`drop_bomb` crate](https://docs.rs/drop_bomb/latest/drop_bomb/): A small
+  utility that panics if dropped unless explicitly defused with `.defuse()`.
+  Comes with a `DebugDropBomb` variant that only activates in debug builds.
+
+</details>

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

@@ -0,0 +1,61 @@
+---
+minutes: 10
+---
+
+# 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>
+
+This example removes the flag from the previous slide and makes the drop method
+panic unconditionally. To avoid that panic on a successful commit, the commit
+method now takes ownership of the transaction and calls
+[`std::mem::forget`](https://doc.rust-lang.org/std/mem/fn.forget.html), which
+prevents the `Drop::drop()` method from running.
+
+If the forgotten value owned heap allocated memory that would normally be freed
+in its `drop()` implementation, one consequence is a memory leak. That is not
+the case for the `Transaction` in the example above, since it does not own any
+heap memory.
+
+We can avoid needing a runtime flag by using `mem::forget()` in a tactical way.
+When the transaction commits successfully, we can defuse the drop bomb by
+calling `std::mem::forget` on the value, which prevents its `Drop`
+implementation from running.
+
+</details>

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

@@ -0,0 +1,69 @@
+---
+minutes: 10
+---
+
+# Drop Guards
+
+A **drop guard** in Rust is a temporary object that performs some kind of
+cleanup when it goes out of scope. In the case of `Mutex`, the `lock` method
+returns a `MutexGuard` that automatically unlocks the mutex on `drop`:
+
+```rust
+struct Mutex {
+    is_locked: bool,
+}
+
+struct MutexGuard<'a> {
+    mutex: &'a mut Mutex,
+}
+
+impl Mutex {
+    fn new() -> Self {
+        Self { is_locked: false }
+    }
+
+    fn lock(&mut self) -> MutexGuard<'_> {
+        self.is_locked = true;
+        MutexGuard { mutex: self }
+    }
+}
+
+impl Drop for MutexGuard<'_> {
+    fn drop(&mut self) {
+        self.mutex.is_locked = false;
+    }
+}
+```
+
+<details>
+
+- The example above shows a simplified `Mutex` and its associated guard.
+
+- Even though it is not a production-ready implementation, it illustrates the
+  core idea:
+
+  - the guard represents exclusive access,
+  - and its `Drop` implementation releases the lock when it goes out of scope.
+
+## More to Explore
+
+This example shows a C++ style mutex that does not contain the data it protects.
+While this is non-idiomatic in Rust, the goal here is only to illustrate the
+core idea of a drop guard, not to demonstrate a proper Rust mutex design.
+
+For brevity, several features are omitted:
+
+- A real `Mutex<T>` stores the protected value inside the mutex.\
+  This toy example omits the value entirely to focus only on the drop guard
+  mechanism.
+- Ergonomic access via `Deref` and `DerefMut` on `MutexGuard` (letting the guard
+  behave like a `&T` or `&mut T`).
+- A fully blocking `.lock()` method and a non-blocking `try_lock` variant.
+
+You can explore the
+[`Mutex` implementation in Rust’s std library](https://doc.rust-lang.org/std/sync/struct.Mutex.html)
+as an example of a production-ready mutex. The
+[`Mutex` from the `parking_lot` crate](https://docs.rs/parking_lot/latest/parking_lot/type.Mutex.html)
+is another worthwhile reference.
+
+</details>