Crate once_cell

source ·
Expand description

Overview

once_cell provides two new cell-like types, unsync::OnceCell and sync::OnceCell. A OnceCell might store arbitrary non-Copy types, can be assigned to at most once and provides direct access to the stored contents. The core API looks roughly like this (and there’s much more inside, read on!):

ⓘ
impl<T> OnceCell<T> {
    const fn new() -> OnceCell<T> { ... }
    fn set(&self, value: T) -> Result<(), T> { ... }
    fn get(&self) -> Option<&T> { ... }
}

Note that, like with RefCell and Mutex, the set method requires only a shared reference. Because of the single assignment restriction get can return a &T instead of Ref<T> or MutexGuard<T>.

The sync flavor is thread-safe (that is, implements the Sync trait), while the unsync one is not.

Recipes

OnceCell might be useful for a variety of patterns.

Safe Initialization of Global Data

use std::{env, io};

use once_cell::sync::OnceCell;

#[derive(Debug)]
pub struct Logger {
    // ...
}
static INSTANCE: OnceCell<Logger> = OnceCell::new();

impl Logger {
    pub fn global() -> &'static Logger {
        INSTANCE.get().expect("logger is not initialized")
    }

    fn from_cli(args: env::Args) -> Result<Logger, std::io::Error> {
       // ...
    }
}

fn main() {
    let logger = Logger::from_cli(env::args()).unwrap();
    INSTANCE.set(logger).unwrap();
    // use `Logger::global()` from now on
}

Lazy Initialized Global Data

This is essentially the lazy_static! macro, but without a macro.

use std::{sync::Mutex, collections::HashMap};

use once_cell::sync::OnceCell;

fn global_data() -> &'static Mutex<HashMap<i32, String>> {
    static INSTANCE: OnceCell<Mutex<HashMap<i32, String>>> = OnceCell::new();
    INSTANCE.get_or_init(|| {
        let mut m = HashMap::new();
        m.insert(13, "Spica".to_string());
        m.insert(74, "Hoyten".to_string());
        Mutex::new(m)
    })
}

There are also the sync::Lazy and unsync::Lazy convenience types to streamline this pattern:

use std::{sync::Mutex, collections::HashMap};
use once_cell::sync::Lazy;

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());
}

Note that the variable that holds Lazy is declared as static, not const. This is important: using const instead compiles, but works wrong.

General purpose lazy evaluation

Unlike lazy_static!, Lazy works with local variables.

use once_cell::unsync::Lazy;

fn main() {
    let ctx = vec![1, 2, 3];
    let thunk = Lazy::new(|| {
        ctx.iter().sum::<i32>()
    });
    assert_eq!(*thunk, 6);
}

If you need a lazy field in a struct, you probably should use OnceCell directly, because that will allow you to access self during initialization.

use std::{fs, path::PathBuf};

use once_cell::unsync::OnceCell;

struct Ctx {
    config_path: PathBuf,
    config: OnceCell<String>,
}

impl Ctx {
    pub fn get_config(&self) -> Result<&str, std::io::Error> {
        let cfg = self.config.get_or_try_init(|| {
            fs::read_to_string(&self.config_path)
        })?;
        Ok(cfg.as_str())
    }
}

Lazily Compiled Regex

This is a regex! macro which takes a string literal and returns an expression that evaluates to a &'static Regex:

macro_rules! regex {
    ($re:literal $(,)?) => {{
        static RE: once_cell::sync::OnceCell<regex::Regex> = once_cell::sync::OnceCell::new();
        RE.get_or_init(|| regex::Regex::new($re).unwrap())
    }};
}

This macro can be useful to avoid the “compile regex on every loop iteration” problem.

Runtime include_bytes!

The include_bytes macro is useful to include test resources, but it slows down test compilation a lot. An alternative is to load the resources at runtime:

use std::path::Path;

use once_cell::sync::OnceCell;

pub struct TestResource {
    path: &'static str,
    cell: OnceCell<Vec<u8>>,
}

impl TestResource {
    pub const fn new(path: &'static str) -> TestResource {
        TestResource { path, cell: OnceCell::new() }
    }
    pub fn bytes(&self) -> &[u8] {
        self.cell.get_or_init(|| {
            let dir = std::env::var("CARGO_MANIFEST_DIR").unwrap();
            let path = Path::new(dir.as_str()).join(self.path);
            std::fs::read(&path).unwrap_or_else(|_err| {
                panic!("failed to load test resource: {}", path.display())
            })
        }).as_slice()
    }
}

static TEST_IMAGE: TestResource = TestResource::new("test_data/lena.png");

#[test]
fn test_sobel_filter() {
    let rgb: &[u8] = TEST_IMAGE.bytes();
    // ...
}

lateinit

LateInit type for delayed initialization. It is reminiscent of Kotlin’s lateinit keyword and allows construction of cyclic data structures:

use once_cell::sync::OnceCell;

pub struct LateInit<T> { cell: OnceCell<T> }

impl<T> LateInit<T> {
    pub fn init(&self, value: T) {
        assert!(self.cell.set(value).is_ok())
    }
}

impl<T> Default for LateInit<T> {
    fn default() -> Self { LateInit { cell: OnceCell::default() } }
}

impl<T> std::ops::Deref for LateInit<T> {
    type Target = T;
    fn deref(&self) -> &T {
        self.cell.get().unwrap()
    }
}

#[derive(Default)]
struct A<'a> {
    b: LateInit<&'a B<'a>>,
}

#[derive(Default)]
struct B<'a> {
    a: LateInit<&'a A<'a>>
}


fn build_cycle() {
    let a = A::default();
    let b = B::default();
    a.b.init(&b);
    b.a.init(&a);

    let _a = &a.b.a.b.a;
}

Comparison with std

!Sync typesAccess ModeDrawbacks
Cell<T>Trequires T: Copy for get
RefCell<T>RefMut<T> / Ref<T>may panic at runtime
unsync::OnceCell<T>&Tassignable only once
Sync typesAccess ModeDrawbacks
AtomicTTworks only with certain Copy types
Mutex<T>MutexGuard<T>may deadlock at runtime, may block the thread
sync::OnceCell<T>&Tassignable only once, may block the thread

Technically, calling get_or_init will also cause a panic or a deadlock if it recursively calls itself. However, because the assignment can happen only once, such cases should be more rare than equivalents with RefCell and Mutex.

Minimum Supported rustc Version

If only the std, alloc, or race features are enabled, MSRV will be updated conservatively, supporting at least latest 8 versions of the compiler. When using other features, like parking_lot, MSRV might be updated more frequently, up to the latest stable. In both cases, increasing MSRV is not considered a semver-breaking change and requires only a minor version bump.

Implementation details

The implementation is based on the lazy_static and lazy_cell crates and std::sync::Once. In some sense, once_cell just streamlines and unifies those APIs.

To implement a sync flavor of OnceCell, this crates uses either a custom re-implementation of std::sync::Once or parking_lot::Mutex. This is controlled by the parking_lot feature (disabled by default). Performance is the same for both cases, but the parking_lot based OnceCell<T> is smaller by up to 16 bytes.

This crate uses unsafe.

F.A.Q.

Should I use the sync or unsync flavor?

Because Rust compiler checks thread safety for you, it’s impossible to accidentally use unsync where sync is required. So, use unsync in single-threaded code and sync in multi-threaded. It’s easy to switch between the two if code becomes multi-threaded later.

At the moment, unsync has an additional benefit that reentrant initialization causes a panic, which might be easier to debug than a deadlock.

Does this crate support async?

No, but you can use async_once_cell instead.

Does this crate support no_std?

Yes, but with caveats. OnceCell is a synchronization primitive which semantically relies on blocking. OnceCell guarantees that at most one f will be called to compute the value. If two threads of execution call get_or_init concurrently, one of them has to wait.

Waiting fundamentally requires OS support. Execution environment needs to understand who waits on whom to prevent deadlocks due to priority inversion. You could make code to compile by blindly using pure spinlocks, but the runtime behavior would be subtly wrong.

Given these constraints, once_cell provides the following options:

  • The race module provides similar, but distinct synchronization primitive which is compatible with no_std. With race, the f function can be called multiple times by different threads, but only one thread will win to install the value.
  • critical-section feature (with a -, not _) uses critical_section to implement blocking.

Can I bring my own mutex?

There is generic_once_cell to allow just that.

Should I use std::cell::OnceCell, once_cell, or lazy_static?

If you can use std version (your MSRV is at least 1.70, and you don’t need extra features once_cell provides), use std. Otherwise, use once_cell. Don’t use lazy_static.

Modules

  • race
    Thread-safe, non-blocking, “first one wins” flavor of OnceCell.
  • sync
    Thread-safe, blocking version of OnceCell.
  • unsync
    Single-threaded version of OnceCell.