# Once in spin::once - Rust
A primitive that provides lazy one-time initialization.
Keywords: rust, rustlang, rust-lang, Once

# 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.

## Trait Implementations

source

### impl<T: Debug> Debug for Once<T>

source

#### fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more

source

### impl<T> Drop for Once<T>

source

#### fn drop(&mut self)

Executes the destructor for this type. Read more

source

### impl<T> From<T> for Once<T>

source

#### fn from(data: T) -> Self

Converts to this type from the input type.

source

### impl<T: Send> Send for Once<T>

source

### impl<T: Send + Sync> Sync for Once<T>

## Auto Trait Implementations

### impl<T> !RefUnwindSafe for Once<T>

### impl<T> Unpin for Once<T> where
T: Unpin,

### impl<T> UnwindSafe for Once<T> where
T: UnwindSafe,

## Blanket Implementations

source

### impl<T> Any for T where
T: 'static + ?Sized,

source

#### fn type_id(&self) -> TypeId

Gets the `TypeId` of `self`. Read more

source

### impl<T> Borrow<T> for T where
T: ?Sized,

const: unstable · source

#### fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more

source

### impl<T> BorrowMut<T> for T where
T: ?Sized,

const: unstable · source

#### fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more

source

### impl<T> From<!> for T

const: unstable · source

#### fn from(t: !) -> T

Converts to this type from the input type.

source

### impl<T> From<T> for T

const: unstable · source

#### fn from(t: T) -> T

Returns the argument unchanged.

source

### impl<T, U> Into<U> for T where
U: From<T>,

const: unstable · source

#### fn into(self) -> U

Calls `U::from(self)`.

That is, this conversion is whatever the implementation of `From<T> for U` chooses to do.

source

### impl<T, U> TryFrom<U> for T where
U: Into<T>,

#### type Error = Infallible

The type returned in the event of a conversion error.

const: unstable · source

#### fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.

source

### impl<T, U> TryInto<U> for T where
U: TryFrom<T>,

#### type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.

const: unstable · source

#### fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.