Struct OnceOptionBox

pub struct OnceOptionBox<T> {
    inner: AtomicPtr<T>,
}

A lazily initialized box. Similar to an Option<Box<T>>, but can be initialized atomically.

It is designed for implementing shared data. Therefore, methods with &self, namely OnceOptionBox::get and the OnceOptionBox::get_or_init methods, only return shared references to the content (&T). The user should use types that support multi-threaded accesses, such as mutexes or atomic types, if the inner type is supposed to be modified concurrently.

Once initialized, this object will own its content. The content is allocated in the heap, and will be dropped and deallocated when this instance is dropped.

Comparison to existing data structures

std::sync::OnceLock also provides thread-safe lazily-initialized cells. But as its name suggests, it uses locks for synchronization, whereas OnceOptionBox is lock-free. OnceLock also has a field of std::sync::Once which increases the space overhead. OnceOptionBox only has one atomic pointer field and is more suitable for large arrays of lazily initialized elements.

Fields

inner: AtomicPtr<T>

Implementations

impl<T> OnceOptionBox<T>

pub fn new() -> OnceOptionBox<T>

Create an empty OnceOptionBox instance.

pub fn get(&self, order: Ordering) -> Option<&T>

Get a reference to the content of this box, or None if not yet initialized.

pub fn get_or_init( &self, order_load: Ordering, order_store: Ordering, init: impl FnOnce() -> T, ) -> &T

Get a reference to the content of this box. If not initialized, it will call init to initialize this box.

When multiple threads attempt to initialize this box concurrently, all threads may call their supplied init closure, but only one thread will successfully initialize this box to the return value of init. Other threads will drop their return values of init. All callers will return the reference to the value created by the successful thread.

Trait Implementations

impl<T> Drop for OnceOptionBox<T>

fn drop(&mut self)

Executes the destructor for this type.

impl<T> Zeroable for OnceOptionBox<T>

fn zeroed() -> Self

Calls zeroed.