lazy_static

In Rust, `static` items are typically initialized at compile time or program startup and require their initial value to be a `const` expression. This means you cannot directly initialize complex types like `std::collections::HashMap`, `std::sync::Mutex`, or `std::sync::RwLock` as `static` variables because their constructors are not `const` functions. Attempting to do so would result in a compile-time error.

The `lazy_static` crate provides a macro, `lazy_static!`, that allows for *lazy initialization* of `static` variables. This means the variable is initialized only when it's first accessed, and all subsequent accesses will use the already initialized value. This initialization is performed in a thread-safe manner, ensuring that the setup code runs exactly once, even in a multi-threaded environment.

How it works:
Internally, `lazy_static` uses mechanisms like `std::sync::Once` (or similar from the `once_cell` crate, which it often depends on) to ensure that the initialization closure is executed precisely once. When the `lazy_static!` macro is used, it defines a static variable that holds an uninitialized state initially. The first time code tries to access this static variable, it triggers the initialization routine. This routine computes the value (e.g., creates the `HashMap` or `Mutex`) and stores it, making it available for all future accesses.

Key Features and Benefits:
1. Complex Static Initialization: It allows static variables to hold complex, non-`const` types that require runtime initialization.
2. Thread-Safe Initialization: The initialization process is guaranteed to be thread-safe, preventing race conditions during the first access.
3. Lazy Evaluation: The initialization code only runs when the static variable is actually used, potentially saving startup time if the static resource isn't always needed.
4. Global State Management: It's commonly used for managing global application configuration, caches, or singletons that need interior mutability (often paired with `Mutex` or `RwLock`).

Usage:
To use `lazy_static`, you typically add it as a dependency in your `Cargo.toml` and then import it using `#[macro_use] extern crate lazy_static;` (for Rust 2015 or older lazy_static versions) or simply `use lazy_static::lazy_static;` (for Rust 2018+ and `lazy_static` 1.0+).

Modern Rust Alternatives:
It's worth noting that Rust 1.70 introduced `std::sync::OnceLock` and `std::sync::OnceCell`, which provide similar lazy initialization capabilities, often without requiring an external crate, especially for non-`static` contexts. The `once_cell` crate also offers more flexible lazy initialization primitives. However, `lazy_static` remains a popular and idiomatic choice for global static variables due to its clear syntax and widespread adoption.

```rust
// First, add this to your Cargo.toml:
// [dependencies]
// lazy_static = "1.4"

#[macro_use] // Required for Rust 2015 edition or older lazy_static versions
extern crate lazy_static;

use std::collections::HashMap;
use std::sync::Mutex;

// Define a lazily initialized static HashMap protected by a Mutex.
// This HashMap will be created and initialized only on its first access.
lazy_static! {
    static ref GLOBAL_CACHE: Mutex<HashMap<String, String>> = {
        let mut map = HashMap::new();
        map.insert("key1".to_string(), "value1".to_string());
        map.insert("key2".to_string(), "value2".to_string());
        map
    };
}

fn main() {
    println!("--- First access to GLOBAL_CACHE ---");

    // Acquire a lock to access the HashMap.
    // The initialization happens here if it hasn't already.
    let mut cache_guard = GLOBAL_CACHE.lock().unwrap();
    println!("Initial cache: {:?}", *cache_guard);

    // Modify the cache
    cache_guard.insert("key3".to_string(), "value3".to_string());
    drop(cache_guard); // Release the lock

    println!("\n--- Second access to GLOBAL_CACHE ---");

    // Acquire the lock again. The HashMap is already initialized.
    let cache_guard = GLOBAL_CACHE.lock().unwrap();
    println!("Updated cache: {:?}", *cache_guard);
    println!("Value for 'key1': {:?}", cache_guard.get("key1"));
    drop(cache_guard); // Release the lock

    println!("\n--- Demonstrating another function accessing the cache ---");
    add_to_cache("new_key".to_string(), "new_value".to_string());
    read_from_cache("new_key".to_string());
    read_from_cache("non_existent_key".to_string());
}

fn add_to_cache(key: String, value: String) {
    let mut cache_guard = GLOBAL_CACHE.lock().unwrap();
    cache_guard.insert(key, value);
    println!("Added to cache. Current cache size: {}", cache_guard.len());
}

fn read_from_cache(key: String) {
    let cache_guard = GLOBAL_CACHE.lock().unwrap();
    match cache_guard.get(&key) {
        Some(val) => println!("Found '{}': {}", key, val),
        None => println!("'{}' not found in cache.", key),
    }
}
```