Struct conquer_once::raw::OnceCell

pub struct OnceCell<T, B> { /* fields omitted */ }

An interior mutability cell type which allows synchronized one-time initialization and read-only access exclusively after initialization.

Methods

impl<T, B> OnceCell<T, B>

pub const fn new() -> Self

Creates a new uninitialized OnceCell.

pub fn into_inner(self) -> Option<T>

Converts self into a Some(T) if the OnceCell has previously been successfully initialized and None otherwise.

Panics

This method panics if the OnceCell has been poisoned.

Examples

let uninit: OnceCell<i32> = OnceCell::new();
assert!(uninit.into_inner().is_none());

let once = OnceCell::new();
once.init_once(|| "initialized");
assert_eq!(once.into_inner(), Some("initialized"));

pub fn is_initialized(&self) -> bool

Returns true if the OnceCell has been successfully initialized.

Notes

This method does not panic if the OnceCell is poisoned.

pub fn is_poisoned(&self) -> bool

Returns true if the OnceCell has been poisoned during initialization.

Notes

This method does not panic if the OnceCell is poisoned.

pub unsafe fn get_unchecked(&self) -> &T

Returns a reference to the inner value without checking whether the OnceCell is actually initialized.

Safety

The caller has to ensure that the cell has been successfully initialized.

Examples

This is one safe way to use this method:

use conquer_once::OnceCell;

// let cell = ...

let res = if cell.is_initialized() {
    Some(unsafe { cell.get_unchecked() })
} else {
    None
};

impl<T, B: Block> OnceCell<T, B>

pub fn init_once(&self, func: impl FnOnce() -> T)

Initializes the OnceCell with func or blocks until it is fully initialized by another thread.

Panics

This method panics if the OnceCell has been poisoned.

Examples

use conquer_once::OnceCell;

let cell = OnceCell::new();
cell.init_once(|| {
    // expensive calculation
    (0..1_000).map(|i| i * i).sum::<usize>()
});

cell.init_once(|| {
    // any further or concurrent calls to `init_once` will do
    // nothing and return immediately with almost no overhead.
});

pub fn try_init_once(
    &self,
    func: impl FnOnce() -> T
) -> Result<(), TryInitError>

Attempts to initialize the OnceCell with func and returns Ok(()) if the initialization closure is successfully executed.

This method never blocks.

Errors

This method fails if the OnceCell is either already initialized or already being initialized by some other thread.

Panics

This method panics if the OnceCell has been poisoned.

Examples

use conquer_once::{OnceCell, TryInitError};

let cell = OnceCell::new();

// .. in thread 1
let res = cell.try_init_once(|| {
    1
});
assert!(res.is_ok());

// .. in thread 2
let res = cell.try_init_once(|| {
    2
});
assert_eq!(res, Err(TryInitError::AlreadyInit));

pub fn get(&self) -> Option<&T>

Returns a reference to the inner value if the OnceCell has been successfully initialized or blocks until an already begun initialization is complete.

Panics

This method panics if the OnceCell has been poisoned.

Examples

use conquer_once::OnceCell;

let cell = OnceCell::new();
assert_eq!(cell.get(), None);
cell.init_once(|| {
    1
});
assert_eq!(cell.get(), Some(&1));

pub fn try_get(&self) -> Result<&T, TryGetError>

Returns a reference to the inner value if the OnceCell has been successfully initialized.

This method never blocks.

Errors

This method fails if the OnceCell is either not initialized or is currently being initialized by some other thread.

Panics

This method panics if the OnceCell has been poisoned.

pub fn get_or_init(&self, func: impl FnOnce() -> T) -> &T

Returns a reference to the inner value if the OnceCell has been successfully initialized and otherwise attempts to call func in order to initialize the OnceCell.

This method is potentially blocking, if another thread is concurrently attempting to initialize the same OnceCell.

Panics

This method panics if the OnceCell has been poisoned.

pub fn try_get_or_init(
    &self,
    func: impl FnOnce() -> T
) -> Result<&T, TryInitError>

Returns a reference to the inner value if the OnceCell has been successfully initialized and otherwise attempts to call func in order to initialize the OnceCell.

Instead of blocking, this method returns a WouldBlock error, if another thread is concurrently attempting to initialize the same OnceCell.

Errors

This method returns an Err if the OnceCell is either not initialized or the thread would have to block.

Panics

This method panics if the OnceCell has been poisoned.

Trait Implementations

impl<T, B> Drop for OnceCell<T, B>

fn drop(&mut self)

Executes the destructor for this type.

impl<T, B> Send for OnceCell<T, B> where
    T: Send, 

impl<T, B> Sync for OnceCell<T, B> where
    T: Sync, 

impl<T: Debug, B> Debug for OnceCell<T, B>

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.