OnceCell

Suppose we have a struct that is expensive to initialize, and might not always be needed. Or we want to wait to initialize it until the last moment possible.

For lazy initialization in Rust, OnceCell is useful. It can help us write logic on a single thread that delays or avoids initializing an expensive type.

Example

Consider this program—like many real-world programs, it has some complicated logic in a function. It can be hard to determine when or if our Test struct is even needed.

use std::cell::OnceCell;

struct Test {
    value: String,
}

fn init_test(i: usize) -> Test {
    // Store value string in struct.
    Test {
        value: i.to_string(),
    }
}

fn main() {
    // Step 1: create OnceCell.
    let test = OnceCell::new();

    // Step 2: pass OnceCell to function.
    compute(&test);
}

fn compute(test: &OnceCell<Test>) {
    // Step 3: loop over some numbers.
    for i in 1..100 {
        // Step 4: if one of two conditions is true, initialize the OnceCell if not already initialized.
        if i == 60 {
            let result = test.get_or_init(|| init_test(i));
            println!("i = 60, value = {}", result.value);
        }
        if i % 61 == 0 {
            let result = test.get_or_init(|| init_test(i));
            println!("i % 61 = 0, value = {}", result.value);
        }
    }
}
i = 60, value = 60
i % 61 = 0, value = 60

Benefits

In a real-world Rust program, we have many functions and conditions. By lazily initializing a struct, we can save resources if the struct is never accessed.

Single-thread

With OnceCell, we do not have a Sync trait so we cannot cross a thread barrier. This means OnceCell can only be used on a single thread, and it cannot be static.

By using OnceCell and its sibling OnceLock, we can simplify and optimize programs. We delay initialization, which means less setup logic is needed, and this can sometimes avoid work altogether.