Struct std::sync::Once1.0.0 [] [src]

pub struct Once { /* fields omitted */ }

A synchronization primitive which can be used to run a one-time global initialization. Useful for one-time initialization for FFI or related functionality. This type can only be constructed with the ONCE_INIT value.


use std::sync::{Once, ONCE_INIT};

static START: Once = ONCE_INIT;

START.call_once(|| {
    // run initialization here


impl Once

Creates a new Once value.

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


use std::sync::{Once, ONCE_INIT};

static mut VAL: usize = 0;
static INIT: Once = ONCE_INIT;

// 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();

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


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.

This is similar to poisoning with mutexes.

🔬 This is a nightly-only experimental API. (once_poison #33577)

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_one_force will no-op.

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



use std::sync::{Once, ONCE_INIT};
use std::thread;

static INIT: Once = ONCE_INIT;

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

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

// call_once_force will still run and reset the poisoned state
INIT.call_once_force(|state| {

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

Trait Implementations

impl Sync for Once

impl Send for Once

impl Debug for Once

Formats the value using the given formatter. Read more