pub struct Once { /* private fields */ }
Expand description
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()
.
Implementations
sourceimpl Once
impl Once
sourcepub fn call_once<F>(&self, f: F)where
F: FnOnce(),
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 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).
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.
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.
sourcepub fn call_once_force<F>(&self, f: F)where
F: FnOnce(&OnceState),
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
.
sourcepub fn is_completed(&self) -> bool
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).