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 or the equivalent Once::new
constructor.
use std::sync::Once;
static START: Once = Once::new();
START.call_once(|| {
});Run
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).
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.
use std::sync::Once;
static mut VAL: usize = 0;
static INIT: Once = Once::new();
fn get_cached_val() -> usize {
unsafe {
INIT.call_once(|| {
VAL = expensive_computation();
});
VAL
}
}
fn expensive_computation() -> usize {
}Run
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
.
#![feature(once_poison)]
use std::sync::Once;
use std::thread;
static INIT: Once = Once::new();
let handle = thread::spawn(|| {
INIT.call_once(|| panic!());
});
assert!(handle.join().is_err());
let handle = thread::spawn(|| {
INIT.call_once(|| {});
});
assert!(handle.join().is_err());
INIT.call_once_force(|state| {
assert!(state.poisoned());
});
INIT.call_once(|| {});Run
🔬 This is a nightly-only experimental API. (
once_is_completed
#54890)
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
It is also possible that immediately after is_completed
returns false, some other thread finishes executing
call_once
.
#![feature(once_is_completed)]
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);Run
#![feature(once_is_completed)]
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);Run
Formats the value using the given formatter. Read more
🔬 This is a nightly-only experimental API. (
try_from
#33417)
The type returned in the event of a conversion error.
🔬 This is a nightly-only experimental API. (
try_from
#33417)
🔬 This is a nightly-only experimental API. (
try_from
#33417)
The type returned in the event of a conversion error.
🔬 This is a nightly-only experimental API. (
try_from
#33417)
Immutably borrows from an owned value. Read more
Mutably borrows from an owned value. Read more
🔬 This is a nightly-only experimental API. (get_type_id
#27745)
this method will likely be replaced by an associated static