Merge branch 'mr/396-rework-rust-essentials-module-error-handling' into 'master'

Resolve "Rework Rust Essentials module: Error handling"

Closes #396

See merge request feng/training/material!530

Author: Dana Binkley

courses/rust_essentials/200_error_handling.rst

@@ -32,11 +32,14 @@ Error Handling
 
 .. container:: PRELUDE END
 
-.. include:: 200_error_handling/01_panics.rst
-.. include:: 200_error_handling/02_result.rst
-.. include:: 200_error_handling/03_try.rst
-.. include:: 200_error_handling/04_try_conversions.rst
-.. include:: 200_error_handling/05_error.rst
-.. include:: 200_error_handling/06_thiserror.rst
-.. include:: 200_error_handling/07_anyhow.rst
-.. include:: 200_error_handling/99_lab.rst
+.. include:: 200_error_handling/00-introduction.rst
+.. include:: 200_error_handling/01-overview.rst
+.. include:: 200_error_handling/02-panic.rst
+.. include:: 200_error_handling/03-result.rst
+.. include:: 200_error_handling/04-try_operator.rst
+.. include:: 200_error_handling/05-try_conversions.rst
+.. include:: 200_error_handling/06-error_trait.rst
+.. include:: 200_error_handling/07-thiserror.rst
+.. include:: 200_error_handling/08-anyhow.rst
+.. include:: 200_error_handling/88-error_handling.lab.rst
+.. include:: 200_error_handling/99-summary.rst

courses/rust_essentials/200_error_handling/00-introduction.rst

@@ -0,0 +1,27 @@
+==============
+Introduction
+==============
+
+----------------
+Topics Covered
+----------------
+
+* **Errors**
+
+  * Unrecoverable errors - :rust:`panic!`
+  * Recoverable Errors - :rust:`Result`
+
+* **Try Operator**
+
+  * Error propagation
+  * Converting error traits
+
+* **Error Trait**
+
+  * Defining error implementations
+
+* **Simplified Error Handling**
+
+  * Creating Errors Through :rust:`derive` - :rust:`thiserror`
+  * :rust:`anyhow`
+

courses/rust_essentials/200_error_handling/01-overview.rst

@@ -0,0 +1,57 @@
+==========
+Overview
+==========
+
+-----------------------
+Rust Error Philosophy
+-----------------------
+
+* Errors are data, not drama!
+
+  * Failures are explicit values
+
+    * Not hidden control flow
+
+* Errors are visible in function signatures
+* Compiler ensures they are handled
+
+  * No access to invalid data
+
+* Failures do not show up mysteriously
+
+  * Visible and enforced
+
+.. list-table::
+  :header-rows: 1
+
+  * - **Language Style**
+    - **Error Visibility**
+
+  * - Exceptions
+    - Hidden control flow
+
+  * - Error codes
+    - Easy to ignore
+
+  * - Error wrappers (e.g., :rust:`Result`)
+    - Explicit and enforced
+
+--------------------------------------
+Expected Errors vs. Logic Violations
+--------------------------------------
+
+* Some errors can be handled by the code
+
+  * File not found
+  * Network timeout
+  * Invalid user input
+
+* Sometimes we just need to reboot the system
+
+  * Impossible state reached
+  * Violated assumptions / invariant
+  * Logic error or other bug
+
+.. note::
+
+  Rust separates bugs from expected failures

courses/rust_essentials/200_error_handling/01_panics.rst

@@ -0,0 +1,105 @@
+=======
+Panic
+=======
+
+---------------------
+Unrecoverable Error
+---------------------
+
+* Runtime errors are not recoverable
+
+  * Failed bounds checks
+
+    * Accessing :rust:`v[100]` on a 3-item vector
+
+  * Logic problems
+
+    * Failed :rust:`assert!` or :rust:`debug_assert!`
+
+* Call :rust:`panic!` when logic indicates unrecoverable error
+
+  * Triggers thread shut-down
+  * Configurable - either unwind stack or abort
+
+------------------------------
+What Happens During a Panic?
+------------------------------
+
+* **Stack unwinding** (default)
+
+  * Rust walks back up the stack and "cleans up"
+
+    * Runs :rust:`drop` for all objects in scope
+
+  * Useful when working with hardware or multiple processes
+
+    * Reset hardware flags
+    * Release any locks
+
+* **Aborting** (configurable)
+
+  * Instantly stops the program
+  * Results in smaller binary size
+
+    * No cleanup code
+
+--------------
+Code Example
+--------------
+
+**Bounds error**
+
+  .. code:: rust
+    :number-lines: 1
+
+    fn main() {
+        let my_vector = vec![10, 20, 30];
+    
+        println!("{}", my_vector[100]); 
+    }
+
+  :error:`thread 'main' (32) panicked at src/main.rs:4:21:`
+
+  :error:`index out of bounds: the len is 3 but the index is 100`
+
+**Manual panic**
+
+  .. code:: rust
+    :number-lines: 1
+
+    fn main() {
+        let my_vector = vec![10, 20, 30];
+
+        if my_vector.len() < 10 {
+            panic!("Vector is too short!");
+        }
+    }
+
+  :error:`thread 'main' (12) panicked at src/main.rs:5:9:`
+
+  :error:`Vector is too short!`
+
+----------------
+When to Panic?
+----------------
+
+* **Prototyping**
+
+  * :rust:`unwrap()` or :rust:`expect()` for quick coding 
+
+    * Replace with proper error handling later
+
+* **Infallible logic** (logic guarantees)
+
+  * In a state that should never occur
+  * Panic indicates a bug
+
+* **Library boundaries**
+
+  * Libraries should return :rust:`Result`
+
+    * User decides how to handle the error
+
+  * Panic if API **contract** is violated
+
+    * E.g., passing an empty list to a function that requires items