1 //! A "once initialization" primitive
3 //! This primitive is meant to be used to run one-time initialization. An
4 //! example use case would be for initializing an FFI library.
6 #[cfg(all(test, not(target_os = "emscripten")))]
10 use crate::panic::{RefUnwindSafe, UnwindSafe};
11 use crate::sys_common::once as sys;
13 /// A synchronization primitive which can be used to run a one-time global
14 /// initialization. Useful for one-time initialization for FFI or related
15 /// functionality. This type can only be constructed with [`Once::new()`].
20 /// use std::sync::Once;
22 /// static START: Once = Once::new();
24 /// START.call_once(|| {
25 /// // run initialization here
28 #[stable(feature = "rust1", since = "1.0.0")]
33 #[stable(feature = "sync_once_unwind_safe", since = "1.59.0")]
34 impl UnwindSafe for Once {}
36 #[stable(feature = "sync_once_unwind_safe", since = "1.59.0")]
37 impl RefUnwindSafe for Once {}
39 /// State yielded to [`Once::call_once_force()`]’s closure parameter. The state
40 /// can be used to query the poison status of the [`Once`].
41 #[stable(feature = "once_poison", since = "1.51.0")]
42 pub struct OnceState {
43 pub(crate) inner: sys::OnceState,
46 /// Initialization value for static [`Once`] values.
51 /// use std::sync::{Once, ONCE_INIT};
53 /// static START: Once = ONCE_INIT;
55 #[stable(feature = "rust1", since = "1.0.0")]
58 note = "the `new` function is now preferred",
59 suggestion = "Once::new()"
61 pub const ONCE_INIT: Once = Once::new();
64 /// Creates a new `Once` value.
66 #[stable(feature = "once_new", since = "1.2.0")]
67 #[rustc_const_stable(feature = "const_once_new", since = "1.32.0")]
69 pub const fn new() -> Once {
70 Once { inner: sys::Once::new() }
73 /// Performs an initialization routine once and only once. The given closure
74 /// will be executed if this is the first time `call_once` has been called,
75 /// and otherwise the routine will *not* be invoked.
77 /// This method will block the calling thread if another initialization
78 /// routine is currently running.
80 /// When this function returns, it is guaranteed that some initialization
81 /// has run and completed (it might not be the closure specified). It is also
82 /// guaranteed that any memory writes performed by the executed closure can
83 /// be reliably observed by other threads at this point (there is a
84 /// happens-before relation between the closure and code executing after the
87 /// If the given closure recursively invokes `call_once` on the same [`Once`]
88 /// instance the exact behavior is not specified, allowed outcomes are
89 /// a panic or a deadlock.
94 /// use std::sync::Once;
96 /// static mut VAL: usize = 0;
97 /// static INIT: Once = Once::new();
99 /// // Accessing a `static mut` is unsafe much of the time, but if we do so
100 /// // in a synchronized fashion (e.g., write once or read all) then we're
103 /// // This function will only call `expensive_computation` once, and will
104 /// // otherwise always return the value returned from the first invocation.
105 /// fn get_cached_val() -> usize {
107 /// INIT.call_once(|| {
108 /// VAL = expensive_computation();
114 /// fn expensive_computation() -> usize {
122 /// The closure `f` will only be executed once if this is called
123 /// concurrently amongst many threads. If that closure panics, however, then
124 /// it will *poison* this [`Once`] instance, causing all future invocations of
125 /// `call_once` to also panic.
127 /// This is similar to [poisoning with mutexes][poison].
129 /// [poison]: struct.Mutex.html#poisoning
131 #[stable(feature = "rust1", since = "1.0.0")]
133 pub fn call_once<F>(&self, f: F)
138 if self.inner.is_completed() {
143 self.inner.call(false, &mut |_| f.take().unwrap()());
146 /// Performs the same function as [`call_once()`] except ignores poisoning.
148 /// Unlike [`call_once()`], if this [`Once`] has been poisoned (i.e., a previous
149 /// call to [`call_once()`] or [`call_once_force()`] caused a panic), calling
150 /// [`call_once_force()`] will still invoke the closure `f` and will _not_
151 /// result in an immediate panic. If `f` panics, the [`Once`] will remain
152 /// in a poison state. If `f` does _not_ panic, the [`Once`] will no
153 /// longer be in a poison state and all future calls to [`call_once()`] or
154 /// [`call_once_force()`] will be no-ops.
156 /// The closure `f` is yielded a [`OnceState`] structure which can be used
157 /// to query the poison status of the [`Once`].
159 /// [`call_once()`]: Once::call_once
160 /// [`call_once_force()`]: Once::call_once_force
165 /// use std::sync::Once;
168 /// static INIT: Once = Once::new();
170 /// // poison the once
171 /// let handle = thread::spawn(|| {
172 /// INIT.call_once(|| panic!());
174 /// assert!(handle.join().is_err());
176 /// // poisoning propagates
177 /// let handle = thread::spawn(|| {
178 /// INIT.call_once(|| {});
180 /// assert!(handle.join().is_err());
182 /// // call_once_force will still run and reset the poisoned state
183 /// INIT.call_once_force(|state| {
184 /// assert!(state.is_poisoned());
187 /// // once any success happens, we stop propagating the poison
188 /// INIT.call_once(|| {});
191 #[stable(feature = "once_poison", since = "1.51.0")]
192 pub fn call_once_force<F>(&self, f: F)
194 F: FnOnce(&OnceState),
197 if self.inner.is_completed() {
202 self.inner.call(true, &mut |p| f.take().unwrap()(p));
205 /// Returns `true` if some [`call_once()`] call has completed
206 /// successfully. Specifically, `is_completed` will return false in
207 /// the following situations:
208 /// * [`call_once()`] was not called at all,
209 /// * [`call_once()`] was called, but has not yet completed,
210 /// * the [`Once`] instance is poisoned
212 /// This function returning `false` does not mean that [`Once`] has not been
213 /// executed. For example, it may have been executed in the time between
214 /// when `is_completed` starts executing and when it returns, in which case
215 /// the `false` return value would be stale (but still permissible).
217 /// [`call_once()`]: Once::call_once
222 /// use std::sync::Once;
224 /// static INIT: Once = Once::new();
226 /// assert_eq!(INIT.is_completed(), false);
227 /// INIT.call_once(|| {
228 /// assert_eq!(INIT.is_completed(), false);
230 /// assert_eq!(INIT.is_completed(), true);
234 /// use std::sync::Once;
237 /// static INIT: Once = Once::new();
239 /// assert_eq!(INIT.is_completed(), false);
240 /// let handle = thread::spawn(|| {
241 /// INIT.call_once(|| panic!());
243 /// assert!(handle.join().is_err());
244 /// assert_eq!(INIT.is_completed(), false);
246 #[stable(feature = "once_is_completed", since = "1.43.0")]
248 pub fn is_completed(&self) -> bool {
249 self.inner.is_completed()
253 #[stable(feature = "std_debug", since = "1.16.0")]
254 impl fmt::Debug for Once {
255 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
256 f.debug_struct("Once").finish_non_exhaustive()
261 /// Returns `true` if the associated [`Once`] was poisoned prior to the
262 /// invocation of the closure passed to [`Once::call_once_force()`].
266 /// A poisoned [`Once`]:
269 /// use std::sync::Once;
272 /// static INIT: Once = Once::new();
274 /// // poison the once
275 /// let handle = thread::spawn(|| {
276 /// INIT.call_once(|| panic!());
278 /// assert!(handle.join().is_err());
280 /// INIT.call_once_force(|state| {
281 /// assert!(state.is_poisoned());
285 /// An unpoisoned [`Once`]:
288 /// use std::sync::Once;
290 /// static INIT: Once = Once::new();
292 /// INIT.call_once_force(|state| {
293 /// assert!(!state.is_poisoned());
295 #[stable(feature = "once_poison", since = "1.51.0")]
297 pub fn is_poisoned(&self) -> bool {
298 self.inner.is_poisoned()
301 /// Poison the associated [`Once`] without explicitly panicking.
302 // NOTE: This is currently only exposed for `OnceLock`.
304 pub(crate) fn poison(&self) {
309 #[stable(feature = "std_debug", since = "1.16.0")]
310 impl fmt::Debug for OnceState {
311 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
312 f.debug_struct("OnceState").field("poisoned", &self.is_poisoned()).finish()