add lazy variant

Author: antouhou

README.md

@@ -15,11 +15,13 @@
   - `Owned` - Heap-allocated owned data via `Box<T>`
   - `Shared` - `Arc<T>` for shared immutable data
   - `Updatable` - Lock-free atomic updates using `arc-swap`
+  - `Lazy` - Lazy initialization with atomic updates for static contexts
 
-- **Lock-Free Updates**: The `Updatable` variant uses `arc-swap` for atomic, lock-free updates
+- **Lock-Free Updates**: The `Updatable` and `Lazy` variants use `arc-swap` for atomic, lock-free updates
+- **Lazy Initialization**: The `Lazy` variant makes it possbile to create an `Updatable` in a static context
 - **Flexible API**: Easy conversion between different storage types
 - **Zero-Cost Abstractions**: Minimal overhead for common operations
-- **Thread-Safe**: Share data safely across threads with `Shared` and `Updatable` variants
+- **Thread-Safe**: Share data safely across threads with `Shared`, `Updatable`, and `Lazy` variants
 
 ## 📦 Installation
 
@@ -35,6 +37,7 @@ anycow = "0.1"
 AnyCow shines in scenarios where you have:
 
 - **Configuration data** that's read frequently but updated occasionally
+- **Global/static data** that needs lazy initialization and atomic updates
 - **Cached values** that need atomic updates without locks
 - **Shared state** across multiple threads with infrequent modifications
 - **Hot paths** where you want to minimize allocation overhead
@@ -50,13 +53,15 @@ let borrowed = AnyCow::borrowed(&"hello");
 let owned = AnyCow::owned(String::from("world"));
 let shared = AnyCow::shared(std::sync::Arc::new(42));
 let updatable = AnyCow::updatable(vec![1, 2, 3]);
+let lazy = AnyCow::lazy(|| vec![7, 8, 9]);
 
 // Read values efficiently
 println!("{}", *borrowed.borrow()); // "hello"
 println!("{}", *owned.borrow());    // "world"
 
 // Atomic updates (lock-free!)
 updatable.try_replace(vec![4, 5, 6]).unwrap();
+lazy.try_replace(vec![10, 11, 12]).unwrap();
 ```
 
 ## 💡 Examples
@@ -130,6 +135,37 @@ cache.try_replace(vec![4, 5, 6, 7, 8]).unwrap();
 reader.join().unwrap();
 ```
 
+### Lazy Global Configuration
+
+```rust
+use anycow::AnyCow;
+use std::collections::HashMap;
+
+// Perfect for static/global data that's expensive to initialize
+static CONFIG: AnyCow<HashMap<String, String>> = AnyCow::lazy(|| {
+    println!("Loading configuration..."); // Only runs once!
+    let mut config = HashMap::new();
+    config.insert("app_name".to_string(), "MyApp".to_string());
+    config.insert("version".to_string(), "1.0.0".to_string());
+    config
+});
+
+fn main() {
+    // First access initializes the config
+    let app_name = CONFIG.borrow().get("app_name").cloned().unwrap();
+    println!("App: {}", app_name);
+    
+    // Subsequent accesses are fast (no re-initialization)
+    let version = CONFIG.borrow().get("version").cloned().unwrap();
+    println!("Version: {}", version);
+    
+    // Update the global config atomically
+    let mut new_config = HashMap::new();
+    new_config.insert("app_name".to_string(), "MyApp Pro".to_string());
+    new_config.insert("version".to_string(), "2.0.0".to_string());
+    CONFIG.try_replace(new_config).unwrap();
+}
+
 ## 🧠 Storage Strategy Guide
 
 | Variant | Best For | Thread Safe | Mutable | Memory |
@@ -138,6 +174,7 @@ reader.join().unwrap();
 | `Owned` | Exclusive ownership | ❌ | ✅ | Heap |
 | `Shared` | Read-only sharing | ✅ | ❌ | Shared |
 | `Updatable` | Concurrent reads + atomic updates | ✅ | Via `try_replace()` | Shared + Atomic |
+| `Lazy` | Static/global data + atomic updates | ✅ | Via `try_replace()` | Lazy + Shared + Atomic |
 
 ## 🔧 API Reference
 
@@ -147,6 +184,7 @@ AnyCow::borrowed(&value)    // From reference
 AnyCow::owned(value)        // From owned value (boxed)
 AnyCow::shared(arc)         // From Arc<T>
 AnyCow::updatable(value)    // Create updatable variant
+AnyCow::lazy(init_fn)       // Create lazy variant with init function
 ```
 
 ### Access
@@ -159,15 +197,16 @@ container.to_arc()          // Convert to Arc<T>
 
 ### Updates
 ```rust
-container.try_replace(new_value)  // Atomic update (Updatable only)
+container.try_replace(new_value)  // Atomic update (Updatable & Lazy only)
 ```
 
 ## ⚡ Performance
 
 AnyCow is designed for performance:
 
 - **Zero-cost borrowing**: No allocation for `Borrowed` variant
-- **Lock-free updates**: `Updatable` uses `arc-swap` for atomic operations
+- **Lazy initialization**: `Lazy` variant allow to create an `Updatable` in a static context
+- **Lock-free updates**: `Updatable` and `Lazy` use `arc-swap` for atomic operations
 - **Minimal overhead**: Smart enum design with efficient memory layout
 - **Branch prediction friendly**: Common operations are optimized
 

examples/const_functions.rs

@@ -0,0 +1,25 @@
+use anycow::AnyCow;
+
+// Lazy initialization works great in static contexts!
+static GLOBAL_CONFIG: AnyCow<Vec<i32>> = AnyCow::lazy(|| vec![1, 2, 3]);
+
+// Borrowed can also be used in const contexts
+const BORROWED_STR: AnyCow<&str> = AnyCow::borrowed(&"hello world");
+
+fn main() {
+    println!("Const functions example:");
+    
+    // Access the borrowed const
+    println!("Borrowed const: {}", *BORROWED_STR.borrow());
+    
+    // First access to lazy initializes it
+    println!("Global config (first access): {:?}", *GLOBAL_CONFIG.borrow());
+    
+    // Update the lazy value atomically
+    GLOBAL_CONFIG.try_replace(vec![4, 5, 6, 7]).unwrap();
+    println!("Global config (after update): {:?}", *GLOBAL_CONFIG.borrow());
+    
+    // Another update
+    GLOBAL_CONFIG.try_replace(vec![8, 9, 10]).unwrap();
+    println!("Global config (final): {:?}", *GLOBAL_CONFIG.borrow());
+}

examples/lazy_demo.rs

@@ -0,0 +1,100 @@
+use anycow::AnyCow;
+use std::collections::HashMap;
+use std::sync::atomic::{AtomicUsize, Ordering};
+
+// Global configuration that's lazily initialized
+static CONFIG: AnyCow<HashMap<String, String>> = AnyCow::lazy(|| {
+    println!("Initializing global config...");
+    let mut config = HashMap::new();
+    config.insert("app_name".to_string(), "MyApp".to_string());
+    config.insert("version".to_string(), "1.0.0".to_string());
+    config.insert("debug".to_string(), "false".to_string());
+    config
+});
+
+// A counter to track how many times expensive computation runs
+static COMPUTATION_COUNTER: AtomicUsize = AtomicUsize::new(0);
+
+// Expensive computation that we want to lazy-load and cache
+static EXPENSIVE_RESULT: AnyCow<Vec<u64>> = AnyCow::lazy(|| {
+    let count = COMPUTATION_COUNTER.fetch_add(1, Ordering::SeqCst);
+    println!("Running expensive computation #{}", count + 1);
+    
+    // Simulate expensive computation
+    (1..=10).map(|i| i * i * i).collect()
+});
+
+fn main() {
+    println!("=== AnyCow Lazy Example ===\n");
+    
+    // 1. Demonstrate that lazy initialization doesn't happen until first access
+    println!("1. Created lazy statics, but nothing initialized yet");
+    println!("   Computation counter: {}\n", COMPUTATION_COUNTER.load(Ordering::SeqCst));
+    
+    // 2. First access to CONFIG initializes it
+    println!("2. First access to CONFIG:");
+    let app_name = CONFIG.borrow().get("app_name").cloned().unwrap_or_default();
+    println!("   App name: {}", app_name);
+    println!("   Computation counter: {}\n", COMPUTATION_COUNTER.load(Ordering::SeqCst));
+    
+    // 3. Subsequent accesses don't re-initialize
+    println!("3. Second access to CONFIG (no re-initialization):");
+    let version = CONFIG.borrow().get("version").cloned().unwrap_or_default();
+    println!("   Version: {}", version);
+    println!("   Computation counter: {}\n", COMPUTATION_COUNTER.load(Ordering::SeqCst));
+    
+    // 4. Update the config atomically
+    println!("4. Updating CONFIG atomically:");
+    let mut new_config = HashMap::new();
+    new_config.insert("app_name".to_string(), "MyApp Pro".to_string());
+    new_config.insert("version".to_string(), "2.0.0".to_string());
+    new_config.insert("debug".to_string(), "true".to_string());
+    new_config.insert("theme".to_string(), "dark".to_string());
+    
+    CONFIG.try_replace(new_config).unwrap();
+    
+    let updated_app_name = CONFIG.borrow().get("app_name").cloned().unwrap_or_default();
+    let theme = CONFIG.borrow().get("theme").cloned().unwrap_or_default();
+    println!("   Updated app name: {}", updated_app_name);
+    println!("   New theme: {}", theme);
+    println!("   Computation counter: {}\n", COMPUTATION_COUNTER.load(Ordering::SeqCst));
+    
+    // 5. Now access the expensive computation for the first time
+    println!("5. First access to EXPENSIVE_RESULT (will initialize):");
+    let result = EXPENSIVE_RESULT.borrow();
+    println!("   Cubes: {:?}", *result);
+    println!("   Computation counter: {}\n", COMPUTATION_COUNTER.load(Ordering::SeqCst));
+    
+    // 6. Access it again (no re-computation)
+    println!("6. Second access to EXPENSIVE_RESULT (no re-computation):");
+    let result2 = EXPENSIVE_RESULT.borrow();
+    println!("   Cubes again: {:?}", *result2);
+    println!("   Computation counter: {}\n", COMPUTATION_COUNTER.load(Ordering::SeqCst));
+    
+    // 7. Update the expensive result
+    println!("7. Updating EXPENSIVE_RESULT:");
+    let new_result: Vec<u64> = (1..=5).map(|i| i * i).collect();
+    EXPENSIVE_RESULT.try_replace(new_result).unwrap();
+    
+    let updated_result = EXPENSIVE_RESULT.borrow();
+    println!("   Updated to squares: {:?}", *updated_result);
+    println!("   Computation counter: {}\n", COMPUTATION_COUNTER.load(Ordering::SeqCst));
+    
+    // 8. Demonstrate local lazy usage
+    println!("8. Local lazy usage:");
+    let local_lazy = AnyCow::lazy(|| {
+        println!("   Initializing local lazy value...");
+        String::from("Hello from local lazy!")
+    });
+    
+    println!("   Created local lazy (not initialized yet)");
+    println!("   Value: {}", *local_lazy.borrow());
+    println!("   Second access: {}", *local_lazy.borrow());
+    
+    println!("\n=== Summary ===");
+    println!("- Lazy initialization only happens on first access");
+    println!("- Subsequent accesses are fast (no re-initialization)");
+    println!("- Atomic updates work just like with Updatable variant");
+    println!("- Perfect for static/const contexts");
+    println!("- Thread-safe and lock-free");
+}