Struct std::sync::Once
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 Once::new()
.
Examples
use std::sync::Once; static START: Once = Once::new(); START.call_once(|| { // run initialization here });
Implementations
impl Once
pub const fn new() -> 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 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 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.
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(|| {});
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);
Trait Implementations
impl Debug for Once
fn fmt(&self, f: &mut Formatter<'_>) -> Result
Formats the value using the given formatter. Read more
impl Send for Once
impl Sync for Once
Auto Trait Implementations
impl !RefUnwindSafe for Once
impl Unpin for Once
impl !UnwindSafe for Once
Blanket Implementations
impl<T> From<T> for T
pub fn from(t: T) -> T
Performs the conversion.
pub fn into(self) -> U
Performs the conversion.
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>
Performs the conversion.
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>
Performs the conversion.
© 2010 The Rust Project Developers
Licensed under the Apache License, Version 2.0 or the MIT license, at your option.
https://doc.rust-lang.org/std/sync/struct.Once.html