once_cell

The Lazy<T, F> type provides a value that is initialized only upon its first access. It is thread-safe and suitable for use in static variables.

Key Methods

• Lazy::new(f): Creates a new lazy value with the provided initializing function f.
• force(&self) -> &T: Explicitly forces evaluation and returns a reference. This is what happens automatically when using Deref.
• force_mut(&mut self) -> &mut T: Forces evaluation and returns a mutable reference.
• get(&self) -> Option<&T>: Returns a reference to the value if it has already been initialized, otherwise None.
• get_mut(&mut self) -> Option<&mut T>: Returns a mutable reference if initialized, otherwise None.
• into_value(self) -> Result<T, F>: Consumes the Lazy instance. Returns Ok(value) if initialized, or Err(f) if it was never initialized. Note: if the Lazy instance was previously 'poisoned' (e.g. via a failed force attempt), this may panic.

Implementation Details

Lazy implements Deref and DerefMut, so you can typically use it as if it were the underlying type T.

use std::collections::HashMap;
use once_cell::sync::Lazy;

static HASHMAP: Lazy<HashMap<i32, String>> = Lazy::new(|| {
    println!("initializing");
    let mut m = HashMap::new();
    m.insert(13, "Spica".to_string());
    m.insert(74, "Hoyten".to_string());
    m
});

fn main() {
    println!("ready");
    std::thread::spawn(|| {
        println!("{:?}", HASHMAP.get(&13));
    }).join().unwrap();
    println!("{:?}", HASHMAP.get(&74));

    // Prints:
    //   ready
    //   initializing
    //   Some("Spica")
    //   Some("Hoyten")
}

The Lazy<T, F> type streamlines the pattern of initializing a value only when it is first used. It is essentially a replacement for the lazy_static! macro but works with local variables as well.

• Global Data: Declare static instances of Lazy to initialize global data.
• Local Data: Use Lazy within functions for general-purpose lazy evaluation.

Note: When using Lazy for global data, declare the variable as static, not const.

Unsync vs Sync: Use once_cell::unsync::Lazy for single-threaded code and once_cell::sync::Lazy for multi-threaded code.

// Global lazy initialization
use once_cell::sync::Lazy;
use std::sync::Mutex;
use std::collections::HashMap;

static GLOBAL_DATA: Lazy<Mutex<HashMap<i32, String>>> = Lazy::new(|| {
    let mut m = HashMap::new();
    m.insert(13, "Spica".to_string());
    m.insert(74, "Hoyten".to_string());
    Mutex::new(m)
});

fn main() {
    println!("{:?}", GLOBAL_DATA.lock().unwrap());
}

The sync::OnceCell<T> is a thread-safe, blocking version of OnceCell. It implements Sync and ensures that reading a non-None value establishes a happens-before relationship with the corresponding write.

Key methods:

• get(&self) -> Option<&T>: Returns the value immediately if initialized, otherwise returns None. This method never blocks.
• wait(&self) -> &T: Blocks the current thread until the cell is initialized, then returns a reference to the value. (Requires std feature).
• set(&self, value: T) -> Result<(), T>: Attempts to initialize the cell. Returns Ok(()) if successful, or Err(value) if already full.

use once_cell::sync::OnceCell;

static CELL: OnceCell<String> = OnceCell::new();

assert!(CELL.get().is_none());

std::thread::spawn(|| {
    assert_eq!(CELL.set("Hello".to_string()), Ok(()));
}).join().unwrap();

assert_eq!(CELL.get().unwrap(), "Hello");

Depending on whether you have mutable or owned access, you can extract the value from a OnceCell:

• take(&mut self) -> Option<T>: Moves the value out of the cell, returning it and leaving the cell in an uninitialized state. If the cell was already empty, it returns None and has no effect.
• into_inner(self) -> Option<T>: Consumes the OnceCell and returns the wrapped value if it was initialized, or None if it was empty.

use once_cell::sync::OnceCell;

// Using take()
let mut cell: OnceCell<String> = OnceCell::new();
assert_eq!(cell.take(), None);

let mut cell = OnceCell::new();
cell.set("hello".to_string()).unwrap();
assert_eq!(cell.take(), Some("hello".to_string()));
assert_eq!(cell.get(), None);

// Using into_inner()
let cell: OnceCell<String> = OnceCell::new();
assert_eq!(cell.into_inner(), None);

let cell = OnceCell::new();
cell.set("hello".to_string()).unwrap();
assert_eq!(cell.into_inner(), Some("hello".to_string()));