Advanced

fn main() {
    let mut num = 5;                     // => num is 5 (type: i32, mutable variable on stack)

    // Create raw pointers (safe operation - no dereference yet)
    let r1 = &num as *const i32;         // => r1 is *const i32 (immutable raw pointer to num's address)
                                         // => Points to stack address of num (e.g., 0x7fff5fbff5bc)
    let r2 = &mut num as *mut i32;       // => r2 is *mut i32 (mutable raw pointer to num's address)
                                         // => Both r1 and r2 point to same memory location
                                         // => Creating raw pointers is SAFE - no borrow checker rules violated

    // Dereference raw pointers (unsafe operation - requires manual verification)
    unsafe {                             // => unsafe block: programmer takes responsibility for safety
        println!("r1: {}", *r1);         // => Dereference r1: reads value 5 from memory
                                         // => Output: r1: 5
                                         // => Safe because r1 points to valid num on stack
        *r2 = 10;                        // => Dereference r2 for write: modifies num through raw pointer
                                         // => num is now 10 (modified via raw pointer, not direct assignment)
        println!("r2: {}", *r2);         // => Dereference r2: reads modified value 10
                                         // => Output: r2: 10
                                         // => Also safe because r2 points to valid mutable num
    }                                    // => All dereferences valid: pointers point to live stack variable

    println!("num after unsafe: {}", num); // => Output: num after unsafe: 10
                                         // => num was modified through r2 raw pointer

    // Invalid pointer (demonstrates undefined behavior - DO NOT DO THIS!)
    let address = 0x012345usize;         // => arbitrary memory address (likely invalid/unmapped)
    let _r = address as *const i32;      // => Cast usize to raw pointer (SAFE - just casting)
                                         // => _r points to potentially invalid memory location
    // unsafe {
    //     println!("{}", *_r);          // => UNDEFINED BEHAVIOR: dereferencing invalid pointer
    //     // => Could segfault, read garbage, or appear to work (unpredictable)
    //     // => No guarantee this address is mapped or contains i32
    //     // => Rust can't verify pointer validity - programmer responsibility
    // }                                 // => NEVER dereference arbitrary addresses!

    // Demonstrating pointer arithmetic (unsafe)
    let arr = [1, 2, 3, 4, 5];           // => Array of 5 i32 elements on stack
    let ptr = arr.as_ptr();              // => ptr is *const i32 pointing to first element (1)
    unsafe {
        println!("First: {}", *ptr);     // => Output: First: 1 (dereference first element)
        let second = ptr.offset(1);      // => Advance pointer by 1 i32 (4 bytes), points to second element
                                         // => Pointer arithmetic requires unsafe (no bounds checking)
        println!("Second: {}", *second); // => Output: Second: 2 (dereference second element)
                                         // => Valid because offset(1) is within array bounds
    }                                    // => offset() out of bounds would be undefined behavior
}

unsafe fn dangerous() {                  // => unsafe function: caller must ensure preconditions
                                         // => Marking function unsafe documents that it has safety requirements
    println!("Doing dangerous things");  // => Simple body - unsafety is in the contract, not implementation
}                                        // => Could access global mutable state, call FFI, etc.

fn split_at_mut(slice: &mut [i32], mid: usize) -> (&mut [i32], &mut [i32]) {
                                         // => Safe function: provides safe abstraction over unsafe code
                                         // => Returns two mutable slices from one - normally violates borrow rules
    let len = slice.len();               // => len is total length (e.g., 6 for vec![1,2,3,4,5,6])
    let ptr = slice.as_mut_ptr();        // => ptr is *mut i32 pointing to first element
                                         // => Getting raw pointer is SAFE - doesn't dereference yet

    assert!(mid <= len);                 // => Runtime safety check: mid must be valid split point
                                         // => Panics if mid > len (prevents out-of-bounds access)
                                         // => This precondition makes the unsafe code below safe

    unsafe {                             // => unsafe block: we've verified mid <= len above
        (
            std::slice::from_raw_parts_mut(ptr, mid),
                                         // => Construct first slice: [0..mid) - ptr to ptr+mid
                                         // => Returns &mut [i32] with mid elements
                                         // => SAFE because: ptr valid, mid <= len, no overlap with second slice
            std::slice::from_raw_parts_mut(ptr.add(mid), len - mid),
                                         // => Construct second slice: [mid..len) - ptr+mid to ptr+len
                                         // => ptr.add(mid) advances pointer by mid elements (mid * size_of::<i32>())
                                         // => Returns &mut [i32] with (len - mid) elements
                                         // => SAFE because: ptr+mid valid, len-mid correct, no overlap with first slice
        )                                // => Returning two &mut slices is safe: they reference disjoint memory
    }                                    // => Function provides safe API - caller doesn't need unsafe block
}

fn main() {
    // Calling unsafe function requires unsafe block
    unsafe {
        dangerous();                     // => Call unsafe function (programmer responsibility for safety)
    }                                    // => Output: Doing dangerous things
                                         // => unsafe block makes it explicit that safety is on us

    // Using safe abstraction (split_at_mut) - no unsafe needed!
    let mut v = vec![1, 2, 3, 4, 5, 6];  // => v is Vec<i32> with 6 elements on heap
    let (left, right) = split_at_mut(&mut v, 3);
                                         // => Split at index 3: left gets [1,2,3], right gets [4,5,6]
                                         // => No unsafe block needed - split_at_mut encapsulates unsafety
                                         // => Both left and right are mutable slices (&mut [i32])
    println!("Left: {:?}", left);        // => Output: Left: [1, 2, 3]
    println!("Right: {:?}", right);      // => Output: Right: [4, 5, 6]

    // Can modify both slices independently (they're disjoint)
    left[0] = 10;                        // => Modify first element of left slice
    right[0] = 40;                       // => Modify first element of right slice
    println!("Modified left: {:?}", left);   // => Output: Modified left: [10, 2, 3]
    println!("Modified right: {:?}", right); // => Output: Modified right: [40, 5, 6]
                                         // => Safe because slices don't overlap (verified by assert in split_at_mut)

    // Compare with std::slice::split_at_mut - same functionality
    let mut v2 = vec![7, 8, 9, 10];      // => Another vector for demonstration
    let (left2, right2) = v2.split_at_mut(2); // => Standard library version (also uses unsafe internally)
    println!("Stdlib left: {:?}", left2);     // => Output: Stdlib left: [7, 8]
    println!("Stdlib right: {:?}", right2);   // => Output: Stdlib right: [9, 10]
}

// Link to C standard library function
extern "C" {                         // => extern "C" block: declare foreign functions with C ABI
    fn abs(input: i32) -> i32;       // => Declare C's abs() function from stdlib.h
                                     // => Signature must match C declaration exactly
                                     // => No function body - implemented in libc
}                                    // => Linker resolves this to system's C library

fn main() {
    // Calling C function is unsafe - no Rust safety guarantees
    unsafe {                         // => unsafe required: C code can do anything
        println!("abs(-3) = {}", abs(-3));
                                     // => Call C's abs() function with -3
                                     // => Output: abs(-3) = 3
                                     // => C function returns absolute value
        let result = abs(-42);       // => result is 42 (C's abs returns i32)
        println!("abs(-42) = {}", result);
                                     // => Output: abs(-42) = 42
    }                                // => Must verify C function is called correctly

    // Example with multiple C functions
    extern "C" {
        fn strlen(s: *const i8) -> usize; // => C's strlen from string.h
                                     // => Takes C string (null-terminated char*)
        fn malloc(size: usize) -> *mut u8; // => C's malloc for heap allocation
        fn free(ptr: *mut u8);       // => C's free to deallocate memory
    }

    unsafe {
        // Call strlen on C string literal
        let c_str = b"Hello\0";      // => Byte string with null terminator (C requirement)
        let len = strlen(c_str.as_ptr() as *const i8);
                                     // => Cast to *const i8 (C's char*)
                                     // => len is 5 (excludes null terminator)
        println!("Length: {}", len); // => Output: Length: 5

        // Allocate memory with malloc (manual memory management!)
        let ptr = malloc(10);        // => Allocate 10 bytes on heap
                                     // => ptr is *mut u8 pointing to heap memory
                                     // => Returns null if allocation fails
        if !ptr.is_null() {          // => Check for allocation failure
            println!("Allocated 10 bytes at {:p}", ptr);
                                     // => Output: Allocated 10 bytes at 0x... (heap address)
            free(ptr);               // => Must manually free to avoid memory leak
                                     // => After free, ptr is dangling - don't use it!
        }
    }
}

// Expose Rust function to C (for calling from C code)
#[no_mangle]                         // => Prevent name mangling: keep function name as "call_from_c"
                                     // => Rust normally mangles names (e.g., _ZN...), C can't find them
pub extern "C" fn call_from_c() {    // => pub: visible to other modules/languages
                                     // => extern "C": use C calling convention (ABI compatibility)
    println!("Called from C!");      // => Can be called from C like: call_from_c();
}                                    // => Returns void (unit type () maps to C's void)

// More complex FFI function: pass data between Rust and C
#[no_mangle]
pub extern "C" fn add_numbers(a: i32, b: i32) -> i32 {
                                     // => C-compatible signature: int add_numbers(int a, int b)
    let result = a + b;              // => result is a + b (e.g., 5 + 3 = 8)
    println!("Rust adding {} + {} = {}", a, b, result);
                                     // => Output: Rust adding 5 + 3 = 8 (if called with 5, 3)
    result                           // => Return i32 to C (compatible with C's int)
}                                    // => C code can call: int sum = add_numbers(5, 3);

// Handling C strings with proper safety
use std::ffi::{CStr, CString};       // => std::ffi types for C string interop

#[no_mangle]
pub extern "C" fn rust_greeting(name: *const i8) -> *mut i8 {
                                     // => Takes C string (*const char), returns C string (*mut char)
    if name.is_null() {              // => Null pointer check (defensive programming)
        return std::ptr::null_mut(); // => Return null if input invalid
    }

    unsafe {
        let c_str = CStr::from_ptr(name); // => Wrap C string in Rust's CStr (borrowed)
                                     // => CStr: borrowed view of null-terminated C string
        let rust_str = c_str.to_str().unwrap_or("Invalid UTF-8");
                                     // => Convert to Rust &str (handles UTF-8 validation)
        let greeting = format!("Hello, {}!", rust_str);
                                     // => greeting is Rust String (e.g., "Hello, Alice!")

        // Convert back to C string for return
        let c_greeting = CString::new(greeting).unwrap();
                                     // => CString: owned null-terminated string
                                     // => Adds null terminator automatically
        c_greeting.into_raw()        // => Transfer ownership to caller (C must call free())
                                     // => Returns *mut i8 for C compatibility
    }                                // => C code responsible for freeing returned pointer
}

static mut COUNTER: u32 = 0;         // => Mutable static: lives for entire program ('static lifetime)
                                     // => Mutable: can be changed by any thread
                                     // => UNSAFE: no synchronization guarantees!

fn add_to_count(inc: u32) {
    unsafe {                         // => unsafe required: accessing mutable static
        COUNTER += inc;              // => Read COUNTER, add inc, write back
                                     // => NOT atomic: race condition if multiple threads!
                                     // => inc is added to current value (e.g., 0 + 3 = 3)
    }                                // => Compiler can't prevent data races here
}

fn main() {
    add_to_count(3);                 // => COUNTER is now 3 (0 + 3)
    add_to_count(7);                 // => COUNTER is now 10 (3 + 7)

    unsafe {                         // => unsafe required: reading mutable static
        println!("COUNTER: {}", COUNTER);
                                     // => Output: COUNTER: 10
                                     // => Reading also unsafe - could be mid-write by another thread
    }

    // Demonstrating the danger: non-atomic read-modify-write
    unsafe {
        let temp = COUNTER;          // => Read current value (10)
        // Imagine thread switch here - another thread could modify COUNTER!
        COUNTER = temp + 5;          // => Write 15 (10 + 5)
                                     // => If another thread modified between read/write, change is lost!
        println!("COUNTER after: {}", COUNTER);
                                     // => Output: COUNTER after: 15
    }
}

// Better approach 1: Atomic types for thread-safe primitives
use std::sync::atomic::{AtomicU32, Ordering};

static ATOMIC_COUNTER: AtomicU32 = AtomicU32::new(0);
                                     // => AtomicU32: thread-safe u32 with atomic operations
                                     // => Immutable static (no mut) - safe to access from any thread
                                     // => Initialized to 0 at program start

fn safe_add_to_count(inc: u32) {
    ATOMIC_COUNTER.fetch_add(inc, Ordering::SeqCst);
                                     // => Atomic read-modify-write (single CPU instruction)
                                     // => fetch_add: atomically adds inc and returns old value
                                     // => Ordering::SeqCst: strongest memory ordering (sequential consistency)
                                     // => No unsafe needed - guaranteed thread-safe!
}

fn demonstrate_atomics() {
    safe_add_to_count(3);            // => Atomically: ATOMIC_COUNTER is now 3
    safe_add_to_count(7);            // => Atomically: ATOMIC_COUNTER is now 10

    let value = ATOMIC_COUNTER.load(Ordering::SeqCst);
                                     // => Atomic read: value is 10
                                     // => No unsafe block needed - safe to read from any thread
    println!("Atomic counter: {}", value);
                                     // => Output: Atomic counter: 10

    ATOMIC_COUNTER.store(20, Ordering::SeqCst);
                                     // => Atomic write: set to 20 (replaces current value)
    println!("After store: {}", ATOMIC_COUNTER.load(Ordering::SeqCst));
                                     // => Output: After store: 20

    // Compare-and-swap (CAS) operation
    let old = ATOMIC_COUNTER.compare_exchange(
        20,                          // => Expected current value (20)
        30,                          // => New value if current matches (30)
        Ordering::SeqCst,            // => Success ordering
        Ordering::SeqCst             // => Failure ordering
    );                               // => Returns Ok(20) if swap succeeded, Err(actual) if failed
    println!("CAS result: {:?}", old); // => Output: CAS result: Ok(20) (swap successful)
    println!("After CAS: {}", ATOMIC_COUNTER.load(Ordering::SeqCst));
                                     // => Output: After CAS: 30
}

// Better approach 2: Mutex for complex data structures
use std::sync::Mutex;
use std::collections::HashMap;

static GLOBAL_MAP: Mutex<Option<HashMap<String, i32>>> = Mutex::new(None);
                                     // => Mutex<T>: locks access to T (thread-safe)
                                     // => Option allows lazy initialization
                                     // => Must be const-initializable (Mutex::new is const)

fn use_global_map() {
    let mut map = GLOBAL_MAP.lock().unwrap();
                                     // => lock() blocks until mutex acquired
                                     // => Returns MutexGuard (RAII lock - auto-releases on drop)
                                     // => unwrap() panics if mutex poisoned (previous thread panicked)

    if map.is_none() {               // => First access: initialize the map
        *map = Some(HashMap::new()); // => Create empty HashMap
    }                                // => map is now Some(HashMap::new())

    if let Some(ref mut m) = *map {  // => Extract mutable reference to HashMap
        m.insert("key".to_string(), 42); // => Insert key-value pair
        println!("Map size: {}", m.len()); // => Output: Map size: 1
    }
}                                    // => MutexGuard dropped: mutex automatically released

// Better approach 3: LazyLock for one-time initialization (Rust 1.80+)
use std::sync::LazyLock;

static LAZY_VALUE: LazyLock<Vec<i32>> = LazyLock::new(|| {
                                     // => LazyLock: thread-safe lazy initialization
    println!("Initializing LAZY_VALUE"); // => Runs once on first access
    vec![1, 2, 3, 4, 5]              // => Returns Vec<i32>
});                                  // => Subsequent accesses return same instance

fn use_lazy_value() {
    println!("{:?}", &*LAZY_VALUE);  // => First access: prints "Initializing..." then [1,2,3,4,5]
    println!("{:?}", &*LAZY_VALUE);  // => Second access: just prints [1,2,3,4,5] (no re-init)
}

#[repr(C)]                           // => C-compatible memory layout (required for FFI unions)
                                     // => Without repr(C), Rust can reorder/optimize layout
union MyUnion {                      // => Union: all fields share same memory location
    f1: u32,                         // => Field 1: 32-bit unsigned integer (4 bytes)
    f2: f32,                         // => Field 2: 32-bit float (4 bytes)
}                                    // => Size of MyUnion is max(sizeof(u32), sizeof(f32)) = 4 bytes
                                     // => Both fields occupy same 4 bytes in memory

fn main() {
    let u = MyUnion { f1: 1 };       // => Initialize union with f1 field set to 1
                                     // => Memory contains: 0x00000001 (as u32 in little-endian)
                                     // => f2 is NOT initialized - reading it is undefined behavior

    unsafe {                         // => All union field access requires unsafe
        println!("u.f1: {}", u.f1);  // => Read f1: safe because we initialized with f1
                                     // => Output: u.f1: 1
                                     // => Memory interpretation: 0x00000001 as u32 = 1

        println!("u.f2: {}", u.f2);  // => Read f2: reinterprets f1's bits as f32!
                                     // => Memory still contains: 0x00000001
                                     // => Interpreted as f32: 0x00000001 ≈ 1.4e-45 (denormal float)
                                     // => Output: u.f2: 0.000000000000000000000000000000000000000000001
                                     // => Reading wrong field = type punning (undefined in Rust!)
    }                                // => Compiler can't track which field is active

    // Demonstrating type punning with more interesting values
    let u2 = MyUnion { f2: 1.0 };    // => Initialize with f2 = 1.0 (floating point)
                                     // => Memory contains: 0x3F800000 (IEEE 754 for 1.0)
    unsafe {
        println!("f2 as float: {}", u2.f2); // => Output: f2 as float: 1.0
        println!("f2 as u32: 0x{:08X}", u2.f1);
                                     // => Read same memory as u32
                                     // => Output: f2 as u32: 0x3F800000 (bit pattern of 1.0f32)
                                     // => Useful for inspecting float representation
    }

    // Practical use case: efficient tagged union (discriminated union)
    #[repr(C)]
    union IntOrFloat {
        i: i32,                      // => Signed 32-bit integer
        f: f32,                      // => 32-bit float
    }

    enum Value {                     // => Tagged union: type-safe wrapper
        Int(i32),                    // => Variant for integer values
        Float(f32),                  // => Variant for float values
    }                                // => Compiler tracks active variant (no unsafe access!)

    // Using enum (safe) vs union (unsafe)
    let safe_value = Value::Int(42); // => Type-safe: compiler knows this is Int
    match safe_value {
        Value::Int(i) => println!("Safe int: {}", i),   // => Pattern matching is safe
        Value::Float(f) => println!("Safe float: {}", f),
    }                                // => Output: Safe int: 42

    let unsafe_value = IntOrFloat { i: 42 }; // => Union: programmer tracks active field
    unsafe {
        println!("Union int: {}", unsafe_value.i);
                                     // => Output: Union int: 42 (correct - we set i)
        // println!("{}", unsafe_value.f); // => WRONG: reading f when i is active!
                                     // => Would give garbage or crash
    }

    // Unions with Copy types only (Rust requirement)
    // union NoCopy {
    //     s: String,                // => ERROR: String is not Copy
    //     v: Vec<i32>,              // => ERROR: Vec is not Copy
    // }                             // => Unions can only contain Copy types (Drop could be ambiguous)

    // FFI use case: matching C union
    #[repr(C)]
    union CUnion {                   // => Matches C's: union { int i; float f; char c[4]; }
        i: i32,                      // => int (4 bytes)
        f: f32,                      // => float (4 bytes)
        c: [u8; 4],                  // => char[4] (4 bytes)
    }                                // => Size: 4 bytes, alignment: 4 bytes (matches C)

    let c_union = CUnion { i: 0x41424344 }; // => Initialize with ASCII "DCBA" (little-endian)
    unsafe {
        println!("As int: 0x{:08X}", c_union.i);
                                     // => Output: As int: 0x41424344
        println!("As bytes: {:?}", c_union.c);
                                     // => Output: As bytes: [68, 67, 66, 65] (D, C, B, A in ASCII)
        println!("As chars: {}",
                 String::from_utf8_lossy(&c_union.c));
                                     // => Output: As chars: DCBA (reinterpret bytes as chars)
    }                                // => Useful for low-level serialization/protocol parsing

    // ManuallyDrop for non-Copy types in unions
    use std::mem::ManuallyDrop;
    union MaybeString {
        s: ManuallyDrop<String>,     // => ManuallyDrop prevents automatic Drop
        i: i32,                      // => Integer alternative
    }                                // => Programmer must manually drop String when done

    let mut u3 = MaybeString { s: ManuallyDrop::new(String::from("Hello")) };
    unsafe {
        println!("String in union: {}", u3.s);
                                     // => Output: String in union: Hello
                                     // => Accessing String through ManuallyDrop
        ManuallyDrop::drop(&mut u3.s); // => Manual Drop call (must do this!)
    }                                // => Without manual drop, String leaks memory
}

macro_rules! vec_from {              // => Define declarative macro named "vec_from"
                                     // => macro_rules! is Rust's declarative macro system
    ( $( $x:expr ),* ) => {          // => Pattern: match comma-separated expressions
                                     // => $(...),* means: repeat pattern for each comma-separated item
                                     // => $x:expr captures each expression (type: expr fragment)
                                     // => , after $x means literal comma separator
                                     // => * means zero or more repetitions
        {                            // => Expansion block: generated code
                                     // => Braces create expression block
            let mut temp_vec = Vec::new(); // => Create empty Vec<T> (type inferred from usage)
                                     // => Mutable because push mutates
            $(                       // => Repetition: repeat for each captured $x
                                     // => Matches * from pattern
                temp_vec.push($x);   // => Push each expression into vector
                                     // => $x replaced with captured expression
            )*                       // => End repetition block
                                     // => Generates one push per input item
            temp_vec                 // => Return the constructed vector
                                     // => Expression without semicolon (return value)
        }
    };                               // => Pattern-expansion pair ends
}                                    // => Macro definition complete

fn main() {                          // => Program entry point
    let v = vec_from![1, 2, 3];      // => Macro invocation: matches pattern with $x = 1, 2, 3
                                     // => Square brackets [] used for macro call
                                     // => Expands to: { let mut temp_vec = Vec::new();
                                     // =>              temp_vec.push(1);
                                     // =>              temp_vec.push(2);
                                     // =>              temp_vec.push(3);
                                     // =>              temp_vec }
                                     // => Type inference: Vec<i32> from pushed integers
                                     // => Expansion happens at compile time
    println!("{:?}", v);             // => Debug formatting for vector
                                     // => Output: [1, 2, 3]

    let v2 = vec_from!["a", "b"];    // => Same macro with different types
                                     // => Pattern matches any expression type
                                     // => Type inference: Vec<&str> from pushed strings
    println!("{:?}", v2);            // => Debug formatting
                                     // => Output: ["a", "b"]
                                     // => Macro is generic through type inference
}                                    // => Vectors dropped, memory freed

// Common pattern: DSL creation (Domain-Specific Language)
macro_rules! hashmap {               // => Macro for HashMap literal syntax
                                     // => Creates DSL for hashmap initialization
    ( $( $key:expr => $val:expr ),* ) => {
                                     // => Pattern: key => value pairs, comma-separated
                                     // => $key:expr captures key expression
                                     // => $val:expr captures value expression
                                     // => => is custom separator token (part of pattern)
                                     // => Allows custom syntax in Rust
        {                            // => Expansion block
            let mut map = std::collections::HashMap::new();
                                     // => Create empty HashMap (types inferred)
                                     // => std::collections::HashMap is full path
            $(                       // => Repeat for each key-value pair
                                     // => Matches * from pattern
                map.insert($key, $val); // => Insert each pair into map
                                     // => $key and $val replaced
            )*                       // => End repetition
                                     // => Generates one insert per pair
            map                      // => Return constructed map
                                     // => Ownership transferred to caller
        }
    };
}

fn use_hashmap_macro() {             // => Function demonstrating hashmap macro
    let map = hashmap![               // => Macro call with key => value syntax
                                     // => DSL syntax looks native to Rust
        "a" => 1,                     // => First pair: "a" (key) => 1 (value)
                                     // => Comma separates pairs
        "b" => 2                      // => Second pair: "b" => 2
                                     // => No trailing comma (optional)
    ];                                // => Type: HashMap<&str, i32>
                                     // => Type inference from usage
    println!("{:?}", map);            // => Debug formatting for HashMap
                                     // => Output: {"a": 1, "b": 2} (or {"b": 2, "a": 1})
                                      // => HashMap iteration order is not guaranteed

    // Using with different types
    let map2 = hashmap![              // => Same macro, different types
                                     // => Macro is type-generic
        1 => "one",                   // => Type: HashMap<i32, &str>
                                     // => Key type i32, value type &str
        2 => "two"                    // => Second pair
    ];
    println!("{:?}", map2);           // => Debug formatting
                                     // => Output: {1: "one", 2: "two"}
}                                    // => Maps dropped, memory freed

// Multiple pattern arms (like match expressions)
macro_rules! create_function {       // => Macro with multiple patterns
                                     // => Works like match expression
    ($func_name:ident) => {           // => First arm: Single identifier pattern
                                      // => Matches function name only (no args)
                                      // => $func_name:ident captures function name
        fn $func_name() {             // => Generate function with captured name
                                     // => No parameters
            println!("Called function {:?}()", stringify!($func_name));
                                      // => stringify! converts ident to string literal
                                      // => Compile-time token-to-string conversion
        }
    };

    ($func_name:ident, $($arg:ident : $arg_type:ty),*) => {
                                      // => Second arm: Pattern with parameters
                                      // => $arg:ident for parameter names
                                      // => $arg_type:ty for parameter types
                                      // => ty fragment matches type syntax
        fn $func_name($($arg: $arg_type),*) {
                                      // => Generate function signature
                                      // => Repeats parameters
            println!("Called function {:?} with args", stringify!($func_name));
                                      // => Generic message (doesn't print args)
        }
    };
}

create_function!(foo);                // => Matches first arm (no args)
                                     // => Expands to: fn foo() { println!(...); }
create_function!(bar, x: i32, y: i32); // => Matches second arm (has args)
                                     // => Expands to: fn bar(x: i32, y: i32) { println!(...); }

fn test_created_functions() {       // => Function to test generated functions
    foo();                            // => Calls generated foo function
                                     // => Output: Called function "foo"()
    bar(1, 2);                        // => Calls generated bar with arguments
                                     // => Output: Called function "bar" with args
}                                    // => Generated functions are real Rust functions

// Demonstrating fragment specifiers
macro_rules! show_fragments {        // => Macro showing different fragment types
                                     // => Multiple arms for different patterns
    ($e:expr) => {                    // => expr: expression (1+2, foo(), etc.)
                                     // => Matches any valid Rust expression
        println!("Expression: {}", $e);
                                     // => Evaluates and prints expression
    };
    ($i:ident) => {                   // => ident: identifier (variable/function name)
                                     // => Matches bare identifiers only
        println!("Identifier: {}", stringify!($i));
                                     // => Converts identifier to string
    };
    ($t:ty) => {                      // => ty: type (i32, String, etc.)
                                     // => Matches type syntax
        println!("Type: {}", stringify!($t));
                                     // => Type converted to string
    };
    ($p:pat) => {                     // => pat: pattern (match arm patterns)
                                     // => Matches pattern syntax
        println!("Pattern: {}", stringify!($p));
                                     // => Pattern converted to string
    };
    ($($x:tt)*) => {                  // => tt: token tree (any token sequence)
                                     // => Most permissive fragment
                                     // => Matches any valid tokens
        println!("Token tree: {}", stringify!($($x)*));
                                     // => Entire token sequence to string
    };
}

// Advanced: recursive macros
macro_rules! count {                 // => Recursive macro for compile-time counting
                                     // => Demonstrates macro recursion
    () => { 0 };                      // => Base case: empty input = 0
                                     // => Terminates recursion
    ($head:expr) => { 1 };            // => Single element = 1
                                     // => Second base case
    ($head:expr, $($tail:expr),*) => { // => Multiple elements (recursive case)
                                     // => $head is first element
                                     // => $tail captures rest
        1 + count!($($tail),*)        // => 1 + count of tail (recursive expansion)
                                     // => Macro calls itself
    };                                // => Compile-time recursion (expanded by compiler)
}                                    // => Recursion depth limited by compiler

fn test_count() {                    // => Function testing count macro
    let n1 = count!();                // => 0 (empty)
                                     // => Matches first base case
    let n2 = count!(1);               // => 1 (single element)
                                     // => Matches second base case
    let n3 = count!(1, 2, 3);         // => 3 (1 + count!(2, 3) = 1 + 1 + 1)
                                     // => Recursively expands: 1 + (1 + (1 + 0))
    println!("Counts: {}, {}, {}", n1, n2, n3);
                                      // => Formats all count results
                                      // => Output: Counts: 0, 1, 3
}                                    // => All compile-time work, zero runtime cost

// Hygiene: macros have lexical scope hygiene
macro_rules! make_binding {          // => Macro demonstrating hygiene
                                     // => Hygiene prevents variable capture
    ($name:ident, $value:expr) => {  // => Captures binding name and value
        let $name = $value;           // => Create binding in macro invocation scope
                                     // => Binding visible at call site
    };
}

fn test_hygiene() {                  // => Function testing macro hygiene
    make_binding!(x, 42);             // => Expands to: let x = 42; (in this scope)
                                     // => Creates x in this function's scope
    println!("x = {}", x);            // => x is accessible in this scope
                                     // => Output: x = 42 (x is accessible here)
                                      // => Hygiene: intermediate variables in macro don't leak
                                     // => Unlike C macros, no unexpected captures
}                                    // => x dropped, scope ends

// In a separate crate (proc-macro = true in Cargo.toml)
// Cargo.toml requires: [lib] proc-macro = true
use proc_macro::TokenStream;         // => TokenStream: stream of tokens from Rust code
                                     // => Input: tokens from item being derived
                                     // => Output: generated Rust code as tokens
use quote::quote;                    // => quote! macro: generate Rust code easily
                                     // => Converts Rust syntax to TokenStream
use syn;                             // => syn: parse TokenStream into AST (Abstract Syntax Tree)
                                     // => Provides data structures for Rust syntax

#[proc_macro_derive(HelloMacro)]     // => Derive macro: generates impl for #[derive(HelloMacro)]
                                     // => Registered name: HelloMacro (used in #[derive(...)])
pub fn hello_macro_derive(input: TokenStream) -> TokenStream {
                                     // => input: tokens from struct/enum being derived
                                     // => Example: struct Pancakes; becomes TokenStream
    let ast = syn::parse(input).unwrap();
                                     // => Parse input TokenStream into DeriveInput AST
                                     // => ast contains: struct name, fields, generics, etc.
                                     // => unwrap() panics on parse error (compile error)
    impl_hello_macro(&ast)           // => Generate impl code, returns TokenStream
}

fn impl_hello_macro(ast: &syn::DeriveInput) -> TokenStream {
                                     // => DeriveInput: parsed representation of item
                                     // => Contains: ident (name), data (fields), generics, attrs
    let name = &ast.ident;           // => Extract struct/enum name (e.g., "Pancakes")
                                     // => Type: &Ident (identifier token)
    let gen = quote! {               // => quote! macro: generates Rust code
                                     // => #name interpolates the identifier
        impl HelloMacro for #name {  // => Generate: impl HelloMacro for Pancakes {
            fn hello_macro() {       // => Method required by HelloMacro trait
                println!("Hello, Macro! My name is {}!", stringify!(#name));
                                     // => stringify!(#name) converts Pancakes to "Pancakes"
            }                        // => Final: println!("Hello, Macro! My name is Pancakes!")
        }
    };                               // => gen is proc_macro2::TokenStream (quote's version)
    gen.into()                       // => Convert to proc_macro::TokenStream (compiler's version)
                                     // => Returns generated impl to compiler
}

// Usage in another crate (the one using the derive)
trait HelloMacro {                   // => Trait that proc macro implements
    fn hello_macro();                // => Method signature (must match macro output)
}

#[derive(HelloMacro)]                // => Invokes hello_macro_derive at compile time
                                     // => Passes "struct Pancakes;" as TokenStream to macro
struct Pancakes;                     // => Zero-sized struct (no fields)
                                     // => Macro generates: impl HelloMacro for Pancakes { ... }

fn main() {
    Pancakes::hello_macro();         // => Call generated method
                                     // => Output: Hello, Macro! My name is Pancakes!
                                     // => Method exists because derive macro generated impl
}

// More complex example: derive with field access
// #[proc_macro_derive(Builder)]
// pub fn derive_builder(input: TokenStream) -> TokenStream {
//     let ast = syn::parse(input).unwrap(); // => Parse struct definition
//     let name = &ast.ident;                // => Get struct name
//     let fields = match &ast.data {
//         syn::Data::Struct(s) => &s.fields, // => Extract fields from struct
//         _ => panic!("Builder only works on structs"),
//     };
//
//     let builder_fields = fields.iter().map(|f| {
//         let name = &f.ident;              // => Field name
//         let ty = &f.ty;                   // => Field type
//         quote! {
//             pub fn #name(mut self, #name: #ty) -> Self {
//                 self.#name = Some(#name);  // => Builder setter method
//                 self
//             }
//         }
//     });                                    // => Generate setter for each field
//
//     let gen = quote! {
//         impl #name {
//             #(#builder_fields)*            // => Repeat setter methods
//         }
//     };
//     gen.into()
// }                                          // => Usage: #[derive(Builder)] struct Config { ... }

// Attribute macro example (different type of proc macro)
// #[proc_macro_attribute]
// pub fn log_calls(attr: TokenStream, item: TokenStream) -> TokenStream {
//                                            // => attr: attributes in #[log_calls(level = "info")]
//                                            // => item: function being annotated
//     let input = syn::parse_macro_input!(item as syn::ItemFn);
//                                            // => Parse as function item
//     let name = &input.sig.ident;           // => Function name
//     let block = &input.block;              // => Function body
//
//     let gen = quote! {
//         fn #name() {
//             println!("Calling function: {}", stringify!(#name));
//             #block                         // => Original function body
//         }
//     };                                     // => Wraps function with logging
//     gen.into()
// }                                          // => Usage: #[log_calls] fn foo() { ... }

// Function-like macro example (third type of proc macro)
// #[proc_macro]
// pub fn sql(input: TokenStream) -> TokenStream {
//                                            // => input: everything inside sql!(...)
//     let query: LitStr = syn::parse(input).unwrap();
//                                            // => Parse as string literal
//     let query_str = query.value();         // => Extract string content
//
//     // Validate SQL at compile time
//     validate_sql(&query_str).expect("Invalid SQL");
//
//     quote! {
//         execute_query(#query)              // => Generate runtime code
//     }.into()
// }                                          // => Usage: sql!("SELECT * FROM users")

use std::time::Duration;             // => Duration: time span (milliseconds, seconds, etc.)

async fn say_hello() {               // => async fn: returns impl Future<Output = ()>
                                     // => Calling this function does NOT execute it immediately
                                     // => Returns a Future that must be .await-ed
    println!("Hello");               // => Executes when future is polled (not at call site)
}                                    // => Future completes immediately (no await points)

async fn say_world() {               // => Another async function
    tokio::time::sleep(Duration::from_millis(100)).await;
                                     // => sleep() returns a Future that completes after 100ms
                                     // => .await suspends execution until Future is ready
                                     // => Yields control to Tokio runtime (non-blocking)
                                     // => Other tasks can run during this 100ms
    println!("World");               // => Executes after 100ms delay
}                                    // => Future<Output = ()> completes after printing

#[tokio::main]                       // => Proc macro: creates Tokio runtime and runs async main
                                     // => Expands to: fn main() { tokio::runtime::Runtime::new()
                                     // =>                .unwrap().block_on(async { ... }) }
async fn main() {                    // => Main is async (requires runtime to execute)
    say_hello().await;               // => Call say_hello(), returns Future
                                     // => .await polls the Future until completion
                                     // => Output: Hello (prints immediately - no await points inside)
                                     // => Execution continues after Future completes

    say_world().await;               // => Call say_world(), returns Future
                                     // => .await starts executing the Future
                                     // => Yields to runtime during sleep (100ms)
                                     // => Output: World (after 100ms delay)
                                     // => Main thread not blocked - runtime can run other tasks
}                                    // => Total time: ~100ms (not 0 + 100 sequentially blocked)

// Demonstrating Future is lazy (does nothing until awaited)
async fn demonstrate_lazy() {
    let future = say_hello();        // => Create Future (NOT executed yet!)
                                     // => No "Hello" printed at this line
    println!("Future created but not executed");
                                     // => Output: Future created but not executed

    future.await;                    // => NOW Future executes
                                     // => Output: Hello (happens here, not at creation)
}

// Multiple await points in single function
async fn multi_step() {
    println!("Step 1");              // => Output: Step 1 (synchronous)

    tokio::time::sleep(Duration::from_millis(50)).await;
                                     // => First await point: yields for 50ms
    println!("Step 2");              // => Output: Step 2 (after 50ms)

    tokio::time::sleep(Duration::from_millis(50)).await;
                                     // => Second await point: yields for another 50ms
    println!("Step 3");              // => Output: Step 3 (after total 100ms)
}                                    // => Function suspends/resumes twice during execution

// Return values from async functions
async fn compute() -> i32 {          // => Returns Future<Output = i32>
    tokio::time::sleep(Duration::from_millis(10)).await;
                                     // => Simulate async work (I/O, network, etc.)
    42                               // => Return value (wrapped in Future)
}

async fn use_computed_value() {
    let result = compute().await;    // => .await unwraps Future to get i32
                                     // => result is i32, not Future<Output = i32>
    println!("Computed: {}", result); // => Output: Computed: 42
                                     // => Can use result directly (no Future wrapper)
}

// Error handling with async
async fn might_fail() -> Result<String, &'static str> {
                                     // => Returns Future<Output = Result<String, &str>>
    tokio::time::sleep(Duration::from_millis(10)).await;
    Ok(String::from("Success"))      // => Return Ok variant
    // Err("Something went wrong")   // => Or Err variant
}

async fn handle_async_result() {
    match might_fail().await {       // => .await gets Result<String, &str>
                                     // => Pattern match on Result (not Future)
        Ok(value) => println!("Got: {}", value),
                                     // => Output: Got: Success
        Err(e) => println!("Error: {}", e),
    }                                // => Error propagation works with ? operator too

    // Using ? operator with async
    // let value = might_fail().await?; // => Propagate error up the call stack
    //                                  // => Works like sync code with Result
}

use tokio::time::{sleep, Duration};  // => sleep: async sleep function
                                     // => Returns Future that completes after duration

async fn do_work(id: u32) -> u32 {   // => Async function: returns Future<Output = u32>
    println!("Task {} started", id); // => Prints when Future is first polled
                                     // => id is captured in the Future (closure-like)
    sleep(Duration::from_millis(100)).await;
                                     // => Suspends for 100ms (non-blocking)
                                     // => Future yields control to executor
    println!("Task {} finished", id); // => Resumes after 100ms, prints completion
    id * 2                           // => Return value: id doubled (e.g., 1 * 2 = 2)
}                                    // => Future completes with value id * 2

#[tokio::main]                       // => Creates Tokio runtime (multi-threaded by default)
                                     // => Runtime has executor that polls Futures
async fn main() {
    // Creating futures (lazy - not executed yet!)
    let future1 = do_work(1);        // => future1 is Future<Output = u32>, NOT executed
                                     // => NO "Task 1 started" printed here
    let future2 = do_work(2);        // => future2 is Future<Output = u32>, NOT executed
                                     // => NO "Task 2 started" printed here
                                     // => Futures are just state machines waiting to be polled

    println!("Futures created, now joining...");
                                     // => Output: Futures created, now joining...
                                     // => Neither future has started yet (lazy evaluation)

    // Futures are lazy - not executed until awaited
    let (result1, result2) = tokio::join!(future1, future2);
                                     // => tokio::join! polls both Futures concurrently
                                     // => Both start executing (prints "Task 1 started", "Task 2 started")
                                     // => When one sleeps, executor polls the other
                                     // => Total time: ~100ms (not 200ms) due to concurrency
                                     // => Output order: "Task 1 started", "Task 2 started",
                                     // =>              (100ms later) "Task 1 finished", "Task 2 finished"
                                     // => result1 is 2 (1 * 2), result2 is 4 (2 * 2)
    println!("Results: {} and {}", result1, result2);
                                     // => Output: Results: 2 and 4
                                     // => Both futures completed, values extracted
}

// Understanding polling mechanism (under the hood)
use std::future::Future;
use std::pin::Pin;
use std::task::{Context, Poll};

// Simplified Future implementation (what async fn generates)
struct DelayedValue {
    value: u32,
    ready: bool,                     // => Tracks if Future is ready
}

impl Future for DelayedValue {       // => Implement Future trait manually
    type Output = u32;               // => Future completes with u32

    fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
                                     // => Executor calls poll() repeatedly
                                     // => cx: contains Waker to notify executor when ready
        if self.ready {              // => Check if Future is ready
            Poll::Ready(self.value)  // => Return Ready with value (Future completes)
        } else {
            self.ready = true;       // => Mark as ready for next poll
            cx.waker().wake_by_ref(); // => Wake executor to poll again
            Poll::Pending            // => Not ready yet, return Pending
        }                            // => Executor will poll again later
    }
}

// Demonstrating sequential vs concurrent execution
async fn demonstrate_timing() {
    use std::time::Instant;

    // Sequential execution (one after another)
    let start = Instant::now();      // => Start timer
    do_work(1).await;                // => Executes first task (100ms)
    do_work(2).await;                // => Then executes second task (100ms)
    let seq_time = start.elapsed();  // => Total: ~200ms (100 + 100)
    println!("Sequential: {:?}", seq_time);
                                     // => Output: Sequential: ~200ms

    // Concurrent execution (both at same time)
    let start = Instant::now();      // => Reset timer
    tokio::join!(do_work(1), do_work(2));
                                     // => Both execute concurrently
    let conc_time = start.elapsed(); // => Total: ~100ms (max of 100 and 100)
    println!("Concurrent: {:?}", conc_time);
                                     // => Output: Concurrent: ~100ms
                                     // => 2x faster with concurrency!
}

// Runtime vs executor vs future relationship
// 1. Runtime (Tokio): provides executor + timer + I/O reactor
// 2. Executor: polls Futures until completion
// 3. Future: state machine that yields when not ready
//
// Flow:
// async fn -> compiler generates Future (state machine)
// .await -> tells executor to poll Future
// Executor -> calls Future::poll() repeatedly
// Future -> returns Pending (yield) or Ready(value) (complete)
// If Pending -> executor schedules Future for later polling
// If Ready -> executor extracts value and continues

use tokio::time::{sleep, Duration};  // => Async sleep (non-blocking)
                                     // => Import Tokio's time utilities for async delays
                                     // => tokio::time::sleep is async equivalent of std::thread::sleep

async fn task1() -> u32 {            // => First async task
                                     // => async keyword makes function return Future
                                     // => Returns Future<Output = u32> when called
                                     // => Function doesn't run until awaited
    sleep(Duration::from_millis(100)).await;
                                     // => Sleep 100ms (yields to runtime)
                                     // => .await suspends this future
                                     // => Suspends execution, allows other tasks to run
                                     // => Non-blocking: thread can do other work
    println!("Task 1 done");         // => Prints after 100ms
                                     // => Resumes execution after sleep completes
    1                                // => Returns 1
                                     // => Return value wrapped in Future
}

async fn task2() -> u32 {            // => Second async task (faster)
                                     // => Returns Future<Output = u32> when called
                                     // => Identical pattern to task1
    sleep(Duration::from_millis(50)).await;
                                     // => Sleep 50ms (yields to runtime)
                                     // => Shorter duration than task1
                                     // => Finishes in half the time of task1
    println!("Task 2 done");         // => Prints after 50ms
                                     // => Will print before task1
    2                                // => Returns 2
                                     // => Different return value
}

#[tokio::main]                       // => Attribute macro: Creates Tokio multi-threaded runtime
                                     // => Transforms main into async context
                                     // => Enables async/await in main function
                                     // => Equivalent to tokio::runtime::Builder setup
async fn main() {                    // => main is now async, returns Future<Output = ()>
                                     // => Attribute makes this the entry point
    // tokio::join! runs futures concurrently on SAME task/thread
    let (r1, r2) = tokio::join!(task1(), task2());
                                     // => tokio::join! is macro for concurrent execution
                                     // => Calls task1() and task2() to create futures
                                     // => Start both tasks at time 0
                                     // => Macro polls both futures cooperatively
                                     // => Destructures results into (r1, r2) tuple
                                     // => t=0ms: both tasks start sleeping
                                     // => Runtime schedules both futures
                                     // => t=50ms: task2 completes, prints "Task 2 done"
                                     // => task1 still sleeping (50ms remaining)
                                     // => t=100ms: task1 completes, prints "Task 1 done"
                                     // => Total time: 100ms (not 150ms - concurrent!)
                                     // => Concurrent execution saves 50ms
                                     // => Output order: "Task 2 done" (first), then "Task 1 done"
                                     // => r1 = 1, r2 = 2 (both values available)
                                     // => Type: (u32, u32) from join! destructuring

    println!("Results: {} + {} = {}", r1, r2, r1 + r2);
                                     // => Formats results into string
                                     // => Output: Results: 1 + 2 = 3
                                     // => Both tasks completed, sum computed
}                                    // => Runtime shuts down after main returns
                                     // => All async tasks must complete before exit

// Demonstrating join! behavior with multiple tasks
async fn multi_join() {              // => Function demonstrating multiple concurrent tasks
                                     // => Shows join! scales to many futures
    use std::time::Instant;          // => Import for timing measurement
                                     // => Instant tracks elapsed time

    async fn work(id: u32, ms: u64) -> u32 {
                                     // => Generic async work function
                                     // => id identifies task, ms is duration
        sleep(Duration::from_millis(ms)).await;
                                     // => Sleeps for specified milliseconds
                                     // => Yields to runtime during sleep
        println!("Task {} done ({}ms)", id, ms);
                                     // => Prints when task completes
                                     // => Order depends on sleep duration
        id                           // => Returns task id
                                     // => Value collected by join!
    }

    let start = Instant::now();      // => Record start time
                                     // => For measuring concurrent execution time
    let (a, b, c, d) = tokio::join!(  // => Join 4 futures concurrently
                                     // => Returns tuple of 4 results
        work(1, 100),                // => Sleeps 100ms
                                     // => Second longest task
        work(2, 50),                 // => Sleeps 50ms (finishes first)
                                     // => Shortest duration
        work(3, 75),                 // => Sleeps 75ms
                                     // => Medium duration
        work(4, 120),                // => Sleeps 120ms (finishes last)
                                     // => Longest duration determines total time
    );                               // => All run concurrently
                                     // => join! polls all futures in rotation
                                     // => Total time: max(100, 50, 75, 120) = 120ms
                                     // => NOT 100+50+75+120 = 345ms (would be sequential)
                                     // => Concurrent execution is 2.87x faster
    let elapsed = start.elapsed();   // => Calculate elapsed time
                                     // => Duration from start to now
    println!("Completed {} tasks in {:?}", a+b+c+d, elapsed);
                                     // => a=1, b=2, c=3, d=4 from work() returns
                                     // => Output: Completed 10 tasks in ~120ms
                                     // => 10 = 1+2+3+4 (all tasks completed)
}                                    // => Demonstrates concurrent efficiency gain

// Comparing join! vs spawn (different concurrency models)
async fn join_vs_spawn() {          // => Demonstrates two concurrency patterns
                                     // => join! vs spawn comparison
    // tokio::join! - same task, cooperative concurrency
    let (r1, r2) = tokio::join!(     // => Concurrent execution on same task
                                     // => Cooperative multitasking
        async { sleep(Duration::from_millis(10)).await; 1 },
                                     // => Inline async block
                                     // => Sleeps 10ms, returns 1
        async { sleep(Duration::from_millis(10)).await; 2 },
                                     // => Second inline async block
                                     // => Sleeps 10ms, returns 2
    );                               // => Both run on SAME async task
                                     // => Yields between tasks when awaiting
                                     // => Single-threaded concurrency (like async/await in JS)
                                     // => Results: r1=1, r2=2
    println!("join!: {} + {}", r1, r2);
                                     // => Output: join!: 1 + 2

    // tokio::spawn - separate tasks, can run on different threads
    let h1 = tokio::spawn(async {    // => Spawns INDEPENDENT task
                                     // => Returns JoinHandle<T>
        sleep(Duration::from_millis(10)).await;
                                     // => Sleep in separate task
        1                            // => Task returns 1
    });                              // => Spawns independent task (like thread::spawn)
                                     // => Task scheduled on runtime thread pool
    let h2 = tokio::spawn(async {    // => Spawns SECOND independent task
        sleep(Duration::from_millis(10)).await;
                                     // => Sleep in another separate task
        2                            // => Task returns 2
    });                              // => Spawns another independent task
                                     // => Can run on different OS threads (if multi-threaded runtime)
                                     // => Both tasks can execute truly parallel on different cores
    let r1 = h1.await.unwrap();      // => Wait for task 1 completion
                                     // => JoinHandle::await returns Result<T, JoinError>
                                     // => unwrap() panics if task panicked
    let r2 = h2.await.unwrap();      // => Wait for task 2 completion
                                     // => Both tasks already running concurrently
    println!("spawn: {} + {}", r1, r2);
                                     // => Output: spawn: 1 + 2
}                                    // => join! for same-task concurrency, spawn for independent tasks

// Error handling with join!
async fn join_with_errors() {       // => Demonstrates error handling with concurrent futures
                                     // => join! doesn't short-circuit on error
    async fn may_fail(id: u32) -> Result<u32, &'static str> {
                                     // => Async function returning Result
                                     // => Simulates fallible async operation
        sleep(Duration::from_millis(10)).await;
                                     // => Simulate async work
        if id == 2 {                 // => Conditional failure
            Err("Task 2 failed!")    // => Second task returns error
                                     // => Error case
        } else {
            Ok(id)                   // => Other tasks succeed
                                     // => Success case returns id
        }
    }

    let (r1, r2, r3) = tokio::join!( // => Join three potentially-failing futures
                                     // => Each result is independent Result<T, E>
        may_fail(1),                 // => Ok(1)
                                     // => First task succeeds
        may_fail(2),                 // => Err("Task 2 failed!")
                                     // => Second task fails
        may_fail(3),                 // => Ok(3)
                                     // => Third task succeeds
    );                               // => All complete, even if some fail
                                     // => join! waits for ALL futures (not short-circuit)
                                     // => Type: (Result<u32, &str>, Result<u32, &str>, Result<u32, &str>)

    println!("Results: {:?}, {:?}, {:?}", r1, r2, r3);
                                     // => Debug formatting for all results
                                     // => Output: Results: Ok(1), Err("Task 2 failed!"), Ok(3)
                                     // => All results available (error doesn't cancel others)
}                                    // => Caller must handle each Result independently

// try_join! - short-circuit on error
async fn try_join_example() {       // => Demonstrates try_join! error handling
                                     // => Different from join!: short-circuits on first error
    async fn may_fail(id: u32) -> Result<u32, &'static str> {
                                     // => Async function returning Result
                                     // => Variable sleep duration based on id
        sleep(Duration::from_millis(10 * id as u64)).await;
                                     // => Sleep duration: id * 10ms
                                     // => id=1: 10ms, id=2: 20ms, id=3: 30ms
        if id == 2 { Err("Failed!") } else { Ok(id) }
                                     // => Task 2 fails, others succeed
    }

    // try_join! returns Result - Err if ANY future fails
    let result = tokio::try_join!(   // => Returns Result<(T, U, V), E>
                                     // => Short-circuits on first error
        may_fail(1),                 // => Ok(1) after 10ms
                                     // => First task succeeds
        may_fail(2),                 // => Err("Failed!") after 20ms
                                     // => Second task fails
        may_fail(3),                 // => Would be Ok(3), but never checked
                                     // => Third task still runs (futures concurrent)
    );                               // => Returns Err as soon as may_fail(2) fails
                                     // => Type: Result<(u32, u32, u32), &'static str>
                                     // => Other futures still run but result ignored

    match result {                   // => Pattern match on Result
        Ok((a, b, c)) => println!("All succeeded: {}, {}, {}", a, b, c),
                                     // => This branch never executes (task 2 fails)
        Err(e) => println!("One failed: {}", e),
                                     // => This branch executes
                                     // => e is "Failed!" from may_fail(2)
                                     // => Output: One failed: Failed!
    }
}                                    // => try_join! for fail-fast concurrent operations