impl Once

const fn new() -> Once

Creates a new Once value.

fn call_once<F>(self: &Self, f: F)
where
    F: FnOnce()

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 might 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).

If the given closure recursively invokes call_once on the same Once instance, the exact behavior is not specified: allowed outcomes are a panic or a deadlock.

Examples

use std::sync::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 {
    // ...
# 2
}

Panics

The closure f will only be executed once even 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.

This is similar to poisoning with mutexes, but this mechanism is guaranteed to never skip panics within f.

fn call_once_force<F>(self: &Self, f: F)
where
    F: FnOnce(&OnceState)

Performs the same function as call_once() except ignores poisoning.

Unlike call_once(), if this Once has been poisoned (i.e., a previous call to call_once() or call_once_force() caused a panic), calling call_once_force() will still invoke the closure f and will not result in an immediate panic. If f panics, the Once will remain in a poison state. If f does not panic, the Once will no longer be in a poison state and all future calls to call_once() or call_once_force() will be no-ops.

The closure f is yielded a OnceState structure which can be used to query the poison status of the Once.

Examples

use std::sync::Once;
use std::thread;

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

// poison the once
let handle = thread::spawn(|| {
    INIT.call_once(|| panic!());
});
assert!(handle.join().is_err());

// poisoning propagates
let handle = thread::spawn(|| {
    INIT.call_once(|| {});
});
assert!(handle.join().is_err());

// call_once_force will still run and reset the poisoned state
INIT.call_once_force(|state| {
    assert!(state.is_poisoned());
});

// once any success happens, we stop propagating the poison
INIT.call_once(|| {});

fn is_completed(self: &Self) -> bool

Returns true if some call_once() call has completed successfully. Specifically, is_completed will return false in the following situations:

• call_once() was not called at all,
• call_once() was called, but has not yet completed,
• the Once instance is poisoned

This function returning false does not mean that Once has not been executed. For example, it may have been executed in the time between when is_completed starts executing and when it returns, in which case the false return value would be stale (but still permissible).

Examples

use std::sync::Once;

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

assert_eq!(INIT.is_completed(), false);
INIT.call_once(|| {
    assert_eq!(INIT.is_completed(), false);
});
assert_eq!(INIT.is_completed(), true);

use std::sync::Once;
use std::thread;

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

assert_eq!(INIT.is_completed(), false);
let handle = thread::spawn(|| {
    INIT.call_once(|| panic!());
});
assert!(handle.join().is_err());
assert_eq!(INIT.is_completed(), false);

fn wait(self: &Self)

Blocks the current thread until initialization has completed.

Example

use std::sync::Once;
use std::thread;

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

let thread = thread::spawn(|| {
    READY.wait();
    println!("everything is ready");
});

READY.call_once(|| println!("performing setup"));

Panics

If this Once has been poisoned because an initialization closure has panicked, this method will also panic. Use wait_force if this behavior is not desired.

fn wait_force(self: &Self)

Blocks the current thread until initialization has completed, ignoring poisoning.

If this Once has been poisoned, this function blocks until it becomes completed, unlike [Once::wait()], which panics in this case.

impl Debug for Once

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

impl Freeze for Once

impl RefUnwindSafe for Once

impl Send for Once

impl Sync for Once

impl Unpin for Once

impl UnsafeUnpin for Once

impl UnwindSafe for Once

impl<T> Any for Once

fn type_id(self: &Self) -> TypeId

impl<T> Borrow for Once

fn borrow(self: &Self) -> &T

impl<T> BorrowMut for Once

fn borrow_mut(self: &mut Self) -> &mut T

impl<T> From for Once

fn from(t: T) -> T

Returns the argument unchanged.

impl<T, U> Into for Once

fn into(self: Self) -> U

Calls U::from(self).

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

impl<T, U> TryFrom for Once

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

impl<T, U> TryInto for Once

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