How does `once_cell::sync::Lazy::force` differ from `force_into` for accessing the initialized value?

Lazy::force borrows the Lazy temporarily to ensure initialization and returns a shared reference to the inner value, while force_into consumes the Lazy entirely and returns ownership of the inner value, transferring it out of the lazy wrapper. force takes &self and returns &T, allowing multiple callers to share access while the Lazy remains in place. force_into takes self by value and returns T, destroying the Lazy wrapper in the process. This distinction matters when you need shared access to a lazily-initialized value versus when you need to take ownership of the initialized value, such as returning it from a function or storing it elsewhere.

The Two Access Patterns

use once_cell::sync::Lazy;
use std::collections::HashMap;
 
static CONFIG: Lazy<HashMap<String, String>> = Lazy::new(|| {
    let mut map = HashMap::new();
    map.insert("host".to_string(), "localhost".to_string());
    map.insert("port".to_string(), "8080".to_string());
    map
});
 
fn access_patterns() {
    // force: Returns a reference, Lazy remains in place
    let config: &HashMap<String, String> = Lazy::force(&CONFIG);
    // CONFIG still exists and can be accessed again
    
    // force_into: Takes ownership, Lazy is consumed
    let config: HashMap<String, String> = Lazy::force_into(CONFIG);
    // CONFIG no longer accessible - it was moved
}

force borrows and returns a reference; force_into consumes and returns ownership.

force: Borrowing Access

use once_cell::sync::Lazy;
 
static CACHE: Lazy<Vec<String>> = Lazy::new(|| {
    println!("Initializing cache...");
    (0..10).map(|i| format!("item_{}", i)).collect()
});
 
fn force_example() {
    // force takes &self, returns &T
    let cache: &Vec<String> = Lazy::force(&CACHE);
    
    // Can be called multiple times
    let cache2: &Vec<String> = Lazy::force(&CACHE);
    
    // Both references point to same data
    assert!(std::ptr::eq(*cache, *cache2));
    
    // Lazy remains accessible
    println!("Cache has {} items", cache.len());
    
    // Can also use Deref - force is called implicitly
    let item = &CACHE[0];  // Auto-derefs and forces
}

force returns a shared reference; the Lazy remains usable.

force_into: Consuming Access

use once_cell::sync::Lazy;
 
fn force_into_example() {
    // Create a local Lazy (not static)
    let lazy_data: Lazy<Vec<String>> = Lazy::new(|| {
        (0..5).map(|i| format!("value_{}", i)).collect()
    });
    
    // force_into takes ownership and returns the inner value
    let data: Vec<String> = Lazy::force_into(lazy_data);
    // lazy_data is consumed - no longer accessible
    
    // Now we own the Vec
    println!("Owned data: {:?}", data);
    
    // Can mutate since we own it
    let mut data = data;
    data.push("new_item".to_string());
}
 
// Note: force_into only works on owned Lazy, not &Lazy
// Cannot call on static Lazy references

force_into requires ownership; it cannot be called on references to static Lazy.

The Ownership Distinction

use once_cell::sync::Lazy;
 
fn ownership_comparison() {
    // Static Lazy - can only use force
    static STATIC_DATA: Lazy<String> = Lazy::new(|| "static".to_string());
    
    // This works - force borrows
    let ref1: &String = Lazy::force(&STATIC_DATA);
    
    // Cannot do this - cannot move out of static
    // let owned: String = Lazy::force_into(STATIC_DATA);
    // Error: cannot move out of static item
    
    // Local Lazy - can use either
    let local_data: Lazy<String> = Lazy::new(|| "local".to_string());
    
    // force_into consumes the Lazy
    let owned: String = Lazy::force_into(local_data);
    // local_data no longer valid
    
    // For local Lazy, can also use force
    let local_data2: Lazy<String> = Lazy::new(|| "local2".to_string());
    let reference: &String = Lazy::force(&local_data2);
    // local_data2 still valid
}

Static Lazy values can only use force; owned Lazy can use either.

Function Return Patterns

use once_cell::sync::Lazy;
use std::collections::HashMap;
 
// Pattern: Return initialized value from function
fn get_config() -> HashMap<String, String> {
    let lazy_config: Lazy<HashMap<String, String>> = Lazy::new(|| {
        let mut map = HashMap::new();
        map.insert("key".to_string(), "value".to_string());
        map
    });
    
    // force_into transfers ownership
    Lazy::force_into(lazy_config)
}
 
// Pattern: Return reference to shared lazy value
static GLOBAL_CONFIG: Lazy<HashMap<String, String>> = Lazy::new(|| {
    HashMap::new()
});
 
fn get_config_ref() -> &'static HashMap<String, String> {
    // force returns reference
    Lazy::force(&GLOBAL_CONFIG)
}
 
fn main() {
    let owned_config = get_config();
    // Can mutate owned_config
    drop(owned_config);
    
    let ref_config = get_config_ref();
    // Cannot mutate, only read
    println!("{:?}", ref_config);
}

Use force_into to return owned values; force for shared references.

Deref vs force

use once_cell::sync::Lazy;
 
static DATA: Lazy<Vec<i32>> = Lazy::new(|| vec![1, 2, 3]);
 
fn deref_vs_force() {
    // Deref implicitly calls force
    let first: &i32 = &DATA[0];
    // Equivalent to:
    let first: &i32 = &Lazy::force(&DATA)[0];
    
    // Deref coercion works
    fn takes_slice(data: &[i32]) {
        println!("Slice: {:?}", data);
    }
    takes_slice(&DATA);  // Deref coercion + force
    
    // force is explicit about initialization timing
    Lazy::force(&DATA);  // Explicit call
    // After this, DATA is initialized
    
    // Deref is ergonomic but implicit
    let _ = &DATA;  // Also forces initialization
}

Deref implicitly calls force; explicit force makes initialization timing clear.

Lazy Initialization Semantics

use once_cell::sync::Lazy;
use std::sync::atomic::{AtomicUsize, Ordering};
 
static INIT_COUNT: AtomicUsize = AtomicUsize::new(0);
static LAZY_VALUE: Lazy<String> = Lazy::new(|| {
    INIT_COUNT.fetch_add(1, Ordering::SeqCst);
    println!("Initializing!");
    "initialized".to_string()
});
 
fn initialization_semantics() {
    println!("Before: {} initializations", INIT_COUNT.load(Ordering::SeqCst));
    
    // force triggers initialization
    let val = Lazy::force(&LAZY_VALUE);
    println!("After force: {} initializations", INIT_COUNT.load(Ordering::SeqCst));
    
    // Subsequent force returns existing value
    let val2 = Lazy::force(&LAZY_VALUE);
    println!("After second force: {} initializations", INIT_COUNT.load(Ordering::SeqCst));
    
    // Only one initialization happened
    assert_eq!(INIT_COUNT.load(Ordering::SeqCst), 1);
}

Both force and force_into trigger initialization exactly once; subsequent calls use cached value.

Thread Safety

use once_cell::sync::Lazy;
use std::thread;
 
static SHARED: Lazy<Vec<i32>> = Lazy::new(|| {
    println!("Initializing in thread {:?}", thread::current().id());
    (0..10).collect()
});
 
fn thread_safety() {
    let handles: Vec<_> = (0..5)
        .map(|_| {
            thread::spawn(|| {
                // force is thread-safe
                let data = Lazy::force(&SHARED);
                println!("Thread {:?} got data", thread::current().id());
                data.len()
            })
        })
        .collect();
    
    // All threads can safely force
    // Initialization happens exactly once
    for handle in handles {
        handle.join().unwrap();
    }
    
    // force_into would require ownership, which static items don't allow
    // Cannot move out of static
}

force is thread-safe for concurrent access; static Lazy cannot use force_into.

When to Use force

use once_cell::sync::Lazy;
use std::collections::HashMap;
 
// Use force when:
// 1. You need shared reference access
// 2. The Lazy is static or borrowed
// 3. Multiple callers need access
 
static REGISTRY: Lazy<HashMap<u32, String>> = Lazy::new(|| {
    HashMap::new()
});
 
fn register(id: u32, name: String) {
    // Cannot modify through force - returns &T
    // Lazy only gives immutable access via force
    let registry = Lazy::force(&REGISTRY);
    // Cannot insert - registry is &HashMap, not &mut
}
 
fn lookup(id: u32) -> Option<&'static String> {
    // force returns reference with 'static lifetime
    Lazy::force(&REGISTRY).get(&id)
}
 
fn use_force() {
    // Initialize on first access
    let registry = Lazy::force(&REGISTRY);
    
    // Can read multiple times
    let _ = Lazy::force(&REGISTRY);
    
    // Can get reference from multiple places
    fn get_ref() -> &'static HashMap<u32, String> {
        Lazy::force(&REGISTRY)
    }
}

Use force for shared, read-only access to static or borrowed Lazy values.

When to Use force_into

use once_cell::sync::Lazy;
use std::collections::HashMap;
 
// Use force_into when:
// 1. You need ownership of the value
// 2. The Lazy is locally owned (not static)
// 3. You're done with lazy initialization
 
fn create_and_consume() -> HashMap<String, String> {
    let lazy_map: Lazy<HashMap<String, String>> = Lazy::new(|| {
        let mut map = HashMap::new();
        map.insert("key".to_string(), "value".to_string());
        map
    });
    
    // Initialize and take ownership
    let map = Lazy::force_into(lazy_map);
    
    // Now we own it completely
    // No more Lazy wrapper, just HashMap
    map
}
 
fn transfer_ownership() {
    let config: Lazy<String> = Lazy::new(|| "config data".to_string());
    
    // Transfer ownership to another function
    let owned: String = Lazy::force_into(config);
    process_config(owned);
}
 
fn process_config(config: String) {
    println!("Processing: {}", config);
}

Use force_into to extract ownership from locally-owned Lazy values.

Memory and Performance

use once_cell::sync::Lazy;
 
fn memory_comparison() {
    // force: No additional allocation
    // Returns reference to existing data
    static DATA: Lazy<Vec<i32>> = Lazy::new(|| vec![1, 2, 3, 4, 5]);
    
    let ref1: &Vec<i32> = Lazy::force(&DATA);
    let ref2: &Vec<i32> = Lazy::force(&DATA);
    // Same allocation, two references
    assert!(std::ptr::eq(ref1, ref2));
    
    // force_into: Consumes the Lazy, gives owned value
    let local: Lazy<Vec<i32>> = Lazy::new(|| vec![1, 2, 3]);
    let owned: Vec<i32> = Lazy::force_into(local);
    // No additional allocation - we take the existing Vec
    // But local Lazy is consumed
    
    // Note: force_into is more efficient than cloning
    // because it transfers ownership rather than copying
}

force is zero-cost after initialization; force_into avoids clones by transferring ownership.

Mutable Access Patterns

use once_cell::sync::Lazy;
use std::sync::Mutex;
 
// Lazy itself doesn't support mutable access via force
// Use Mutex for interior mutability
static MUTEX_DATA: Lazy<Mutex<Vec<String>>> = Lazy::new(|| {
    Mutex::new(vec!["initial".to_string()])
});
 
fn mutable_pattern() {
    // Get reference to Mutex
    let data = Lazy::force(&MUTEX_DATA);
    
    // Lock for mutation
    let mut guard = data.lock().unwrap();
    guard.push("new item".to_string());
    
    // Alternative: Lazy<Mutex<T>> with deref
    MUTEX_DATA.lock().unwrap().push("another".to_string());
}
 
// force_into doesn't help with mutability
// But if you own the Lazy, you can get &mut via force_mut
fn local_mutable() {
    let mut lazy_vec: Lazy<Vec<String>> = Lazy::new(|| vec!["item".to_string()]);
    
    // force_mut requires &mut self
    let vec_ref: &mut Vec<String> = Lazy::force_mut(&mut lazy_vec);
    vec_ref.push("mutated".to_string());
    
    // Or consume entirely
    let owned: Vec<String> = Lazy::force_into(lazy_vec);
}

Lazy provides force_mut(&mut self) -> &mut T for mutable access when you own the Lazy.

Real Example: Configuration

use once_cell::sync::Lazy;
use std::collections::HashMap;
use std::env;
 
// Static configuration loaded once
static CONFIG: Lazy<HashMap<String, String>> = Lazy::new(|| {
    let mut config = HashMap::new();
    // Load from environment, files, etc.
    config.insert("host".to_string(), 
        env::var("HOST").unwrap_or_else(|_| "localhost".to_string()));
    config.insert("port".to_string(),
        env::var("PORT").unwrap_or_else(|_| "8080".to_string()));
    config
});
 
fn use_config() {
    // force is appropriate here - shared access
    let config = Lazy::force(&CONFIG);
    
    // Read-only access is common for config
    let host = config.get("host").unwrap();
    let port = config.get("port").unwrap();
    println!("Server at {}:{}", host, port);
    
    // force_into would be inappropriate for static config
    // Cannot move out of static
}
 
// For owned configuration, force_into makes sense
fn load_owned_config() -> HashMap<String, String> {
    let config: Lazy<HashMap<String, String>> = Lazy::new(|| {
        // Complex initialization logic
        HashMap::new()
    });
    
    // Take ownership
    Lazy::force_into(config)
}

Static configuration typically uses force; owned values can use force_into.

Real Example: Caching

use once_cell::sync::Lazy;
use std::collections::HashMap;
use std::fs;
 
// Cached file contents
static FILE_CACHE: Lazy<HashMap<String, String>> = Lazy::new(|| {
    let mut cache = HashMap::new();
    // Pre-populate cache
    if let Ok(contents) = fs::read_to_string("data.txt") {
        cache.insert("data.txt".to_string(), contents);
    }
    cache
});
 
fn get_cached_file(name: &str) -> Option<&'static String> {
    // force gives reference with 'static lifetime
    FILE_CACHE.get(name)
}
 
// For one-time processing, force_into transfers ownership
fn process_files() -> HashMap<String, String> {
    let cache: Lazy<HashMap<String, String>> = Lazy::new(|| {
        // Expensive one-time computation
        HashMap::new()
    });
    
    // Take the cache, process it elsewhere
    Lazy::force_into(cache)
}

Use force for shared cached data; force_into when transferring ownership.

Lazy vs OnceLock

use once_cell::sync::{Lazy, OnceLock};
 
// Lazy: Initialization function stored
static LAZY_DATA: Lazy<Vec<i32>> = Lazy::new(|| {
    println!("Computing...");
    vec![1, 2, 3]
});
 
// OnceLock: Value set explicitly
static ONCE_DATA: OnceLock<Vec<i32>> = OnceLock::new();
 
fn comparison() {
    // Lazy::force returns reference
    let lazy_ref: &Vec<i32> = Lazy::force(&LAZY_DATA);
    
    // OnceLock::get returns Option<&T>
    let once_ref: Option<&Vec<i32>> = ONCE_DATA.get();
    
    // OnceLock::get_or_init is similar to Lazy::force
    let once_ref: &Vec<i32> = ONCE_DATA.get_or_init(|| vec![1, 2, 3]);
    
    // Neither allows taking ownership from static
    // Both provide shared references
    
    // For owned values, use local instances
    let local_lazy: Lazy<Vec<i32>> = Lazy::new(|| vec![1, 2, 3]);
    let owned: Vec<i32> = Lazy::force_into(local_lazy);
}

Lazy stores initialization closure; OnceLock is set explicitly. Both provide shared access.

Synthesis

Quick reference:

use once_cell::sync::Lazy;
 
static STATIC_DATA: Lazy<String> = Lazy::new(|| "static".to_string());
 
fn quick_reference() {
    // force: &Lazy<T> -> &T
    // - Takes reference, returns reference
    // - Lazy remains usable
    // - Works on static Lazy
    // - Thread-safe initialization
    let ref1: &String = Lazy::force(&STATIC_DATA);
    
    // force_into: Lazy<T> -> T
    // - Takes ownership, returns owned value
    // - Lazy is consumed
    // - Requires owned Lazy (not static)
    // - Transfers ownership efficiently
    
    let local: Lazy<String> = Lazy::new(|| "local".to_string());
    let owned: String = Lazy::force_into(local);
    // local is consumed
    
    // Key differences:
    // - force: borrow vs force_into: ownership transfer
    // - force: returns &T vs force_into: returns T
    // - force: works on static vs force_into: needs owned
    // - force: multiple access vs force_into: single use
}

Key insight: force and force_into represent two ownership models for accessing lazily-initialized values. force borrows the Lazy and returns a shared reference—this is the primary pattern for static Lazy values, which cannot be moved from. force_into consumes the Lazy and returns ownership of the inner value—this is useful when you have an owned Lazy and want to extract the value without cloning. The choice depends entirely on ownership: static or borrowed Lazy must use force, while owned Lazy can use either depending on whether you need a shared reference (force) or full ownership (force_into). Use force for shared, read-only access patterns and force_into when transferring ownership of the initialized value.

How does once_cell::sync::Lazy::force differ from force_into for accessing the initialized value?