Once in std::sync - Rust
Description: A low-level synchronization primitive for one-time global execution.

## Once

# Struct Once

1.0.0 · Source

    pub struct Once { /* private fields */ }

Expand description

A low-level synchronization primitive for one-time global execution.

Previously this was the only “execute once” synchronization in `std`. Other libraries implemented novel synchronizing types with `Once`, like `OnceLock<T>` or `LazyLock<T, F>`, before those were added to `std`. `OnceLock<T>` in particular supersedes `Once` in functionality and should be preferred for the common case where the `Once` is associated with data.

This type can only be constructed with `Once::new()`.

## §Examples

    use std::sync::Once;

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

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

## Implementations§

Source§

### impl Once

1.2.0 (const: 1.32.0) · Source

#### pub const fn new() -> Once

Creates a new `Once` value.

1.0.0 · Source

#### pub fn call_once<F>(&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 {
        // ...
    }

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

1.51.0 · Source

#### pub fn call_once_force<F>(&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(|| {});

1.43.0 · Source

#### pub fn is_completed(&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);

1.86.0 · Source

#### pub fn wait(&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.

1.86.0 · Source

#### pub fn wait_force(&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.

## Trait Implementations§

1.16.0 · Source§

### impl Debug for Once

Source§

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

Formats the value using the given formatter. Read more
1.59.0 · Source§

### impl RefUnwindSafe for Once

1.59.0 · Source§

### impl UnwindSafe for Once

## Auto Trait Implementations§

§

### impl !Freeze for Once

§

### impl Send for Once

§

### impl Sync for Once

§

### impl Unpin for Once

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

Source§

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

Immutably borrows from an owned value. Read more
Source§

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

Source§

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

Mutably borrows from an owned value. Read more
Source§

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

Source§

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

Returns the argument unchanged.

Source§

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

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>,

Source§

#### type Error = Infallible

The type returned in the event of a conversion error.
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>,

Source§

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

The type returned in the event of a conversion error.
Source§

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

Performs the conversion.