Struct spin::once::Once

source · [−]

pub struct Once<T> { /* private fields */ }

Expand description

A primitive that provides lazy one-time initialization.

Unlike its std::sync equivalent, this is generalized such that the closure returns a value to be stored by the Once (std::sync::Once can be trivially emulated with Once<()>).

Because Once::new is const, this primitive may be used to safely initialize statics.

Examples

use spin;

static START: spin::Once<()> = spin::Once::new();

START.call_once(|| {
    // run initialization here
});

Implementations

source

impl<T> Once<T>

source

pub const INIT: Self

Initialization constant of Once.

source

pub const fn new() -> Once<T>

Creates a new Once.

source

pub const fn initialized(data: T) -> Once<T>

Creates a new initialized Once.

source

pub fn call_once<F: FnOnce() -> T>(&self, f: F) -> &T

Performs an initialization routine once and only once. The given closure will be executed if this is the first time call_once has been called, and otherwise the routine will not be invoked.

This method will block the calling thread if another initialization routine is currently running.

When this function returns, it is guaranteed that some initialization has run and completed (it may not be the closure specified). The returned pointer will point to the result from the closure that was run.

Panics

This function will panic if the Once previously panicked while attempting to initialize. This is similar to the poisoning behaviour of std::sync’s primitives.

Examples

use spin;

static INIT: spin::Once<usize> = spin::Once::new();

fn get_cached_val() -> usize {
    *INIT.call_once(expensive_computation)
}

fn expensive_computation() -> usize {
    // ...
}

source

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

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

source

pub fn get_mut(&mut self) -> Option<&mut T>

Returns a mutable reference to the inner value if the Once has been initialized.

Because this method requires a mutable reference to the Once, no synchronization overhead is required to access the inner value. In effect, it is zero-cost.

source

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

Returns a the inner value if the Once has been initialized.

Because this method requires ownershup of the Once, no synchronization overhead is required to access the inner value. In effect, it is zero-cost.

source

pub fn is_completed(&self) -> bool

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

source

pub fn wait(&self) -> &T

Spins until the Once contains a value.

Note that in releases prior to 0.7, this function had the behaviour of Once::poll.

Panics

This function will panic if the Once previously panicked while attempting to initialize. This is similar to the poisoning behaviour of std::sync’s primitives.

source

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

Like Once::get, but will spin if the Once is in the process of being initialized. If initialization has not even begun, None will be returned.

Note that in releases prior to 0.7, this function was named wait.

Panics

This function will panic if the Once previously panicked while attempting to initialize. This is similar to the poisoning behaviour of std::sync’s primitives.