# Struct parking_lot::Once [−] [src]

    pub struct Once(_);

A synchronization primitive which can be used to run a one-time initialization. Useful for one-time initialization for globals, FFI or related functionality.

# Differences from the standard library `Once`

- Only requires 1 byte of space, instead of 1 word.
- Not required to be `'static`.
- Relaxed memory barriers in the fast path, which can significantly improve performance on some architectures.
- Efficient handling of micro-contention using adaptive spinning.

# Examples

    use parking_lot::Once;

    static START: Once = Once::new();

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

## Implementations

### `impl Once` [src]

#### `pub const fn new() -> Once` [src]

Creates a new `Once` value.

#### `pub fn state(&self) -> OnceState` [src]

Returns the current state of this `Once`.

#### `pub fn call_once<F>(&self, f: F) where
F: FnOnce(),` [src]

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). It is also guaranteed that any memory writes performed by the executed closure can be reliably observed by other threads at this point (there is a happens-before relation between the closure and code executing after the return).

# Examples

    use parking_lot::Once;

    static mut VAL: usize = 0;
    static INIT: Once = Once::new();

    // Accessing a `static mut` is unsafe much of the time, but if we do so
    // in a synchronized fashion (e.g. write once or read all) then we're
    // good to go!
    //
    // This function will only call `expensive_computation` once, and will
    // otherwise always return the value returned from the first invocation.
    fn get_cached_val() -> usize {
        unsafe {
            INIT.call_once(|| {
                VAL = expensive_computation();
            });
            VAL
        }
    }

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

# Panics

The closure `f` will only be executed once if this is called concurrently amongst many threads. If that closure panics, however, then it will poison this `Once` instance, causing all future invocations of `call_once` to also panic.

#### `pub fn call_once_force<F>(&self, f: F) where
F: FnOnce(OnceState),` [src]

Performs the same function as `call_once` except ignores poisoning.

If this `Once` has been poisoned (some initialization panicked) then this function will continue to attempt to call initialization functions until one of them doesn’t panic.

The closure `f` is yielded a structure which can be used to query the state of this `Once` (whether initialization has previously panicked or not).

## Trait Implementations

### `impl Debug for Once` [src]

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

Formats the value using the given formatter. Read more

### `impl Default for Once` [src]

#### `fn default() -> Once` [src]

Returns the “default value” for a type. Read more

## Auto Trait Implementations

### `impl RefUnwindSafe for Once`

### `impl Send for Once`

### `impl Sync for Once`

### `impl Unpin for Once`

### `impl UnwindSafe for Once`

## Blanket Implementations

### `impl<T> Any for T where
T: 'static + ?Sized,` [src]

#### `pub fn type_id(&self) -> TypeId` [src]

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

### `impl<T> Borrow<T> for T where
T: ?Sized,` [src]

#### `pub fn borrow(&self) -> &T` [src]

Immutably borrows from an owned value. Read more

### `impl<T> BorrowMut<T> for T where
T: ?Sized,` [src]

#### `pub fn borrow_mut(&mut self) -> &mut T` [src]

Mutably borrows from an owned value. Read more

### `impl<T> From<T> for T` [src]

#### `pub fn from(t: T) -> T` [src]

Performs the conversion.

### `impl<T, U> Into<U> for T where
U: From<T>,` [src]

#### `pub fn into(self) -> U` [src]

Performs the conversion.

### `impl<T, U> TryFrom<U> for T where
U: Into<T>,` [src]

#### `type Error = Infallible`

The type returned in the event of a conversion error.

#### `pub fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>` [src]

Performs the conversion.

### `impl<T, U> TryInto<U> for T where
U: TryFrom<T>,` [src]

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

The type returned in the event of a conversion error.

#### `pub fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>` [src]

Performs the conversion.