std: suggest OnceLock over Once · model-checking/verify-rust-std@2678593 (original) (raw)

2 files changed

lines changed

Original file line number Diff line number Diff line change
@@ -133,7 +133,8 @@
133 133 //! - [`Mutex`]: Mutual Exclusion mechanism, which ensures that at
134 134 //! most one thread at a time is able to access some data.
135 135 //!
136 -//! - [`Once`]: Used for a thread-safe, one-time global initialization routine
136 +//! - [`Once`]: Used for a thread-safe, one-time global initialization routine.
137 +//! Mostly useful for implementing other types like `OnceLock`.
137 138 //!
138 139 //! - [`OnceLock`]: Used for thread-safe, one-time initialization of a
139 140 //! variable, with potentially different initializers based on the caller.
Original file line number Diff line number Diff line change
@@ -10,9 +10,15 @@ use crate::fmt;
10 10 use crate::panic::{RefUnwindSafe, UnwindSafe};
11 11 use crate::sys::sync as sys;
12 12
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()`].
13 +/// A low-level synchronization primitive for one-time global execution.
14 +///
15 +/// Previously this was the only "execute once" synchronization in `std`.
16 +/// Other libraries implemented novel synchronizing types with `Once`, like
17 +/// [`OnceLock`] or [`LazyLock<T, F>`], before those were added to `std`.
18 +/// `OnceLock` in particular supersedes `Once` in functionality and should
19 +/// be preferred for the common case where the `Once` is associated with data.
20 +///
21 +/// This type can only be constructed with [`Once::new()`].
16 22 ///
17 23 /// # Examples
18 24 ///
@@ -25,6 +31,9 @@ use crate::sys::sync as sys;
25 31 /// // run initialization here
26 32 /// });
27 33 /// ```
34 +///
35 +/// [`OnceLock`]: crate::sync::OnceLock
36 +/// [`LazyLock<T, F>`]: crate::sync::LazyLock
28 37 #[stable(feature = "rust1", since = "1.0.0")]
29 38 pub struct Once {
30 39 inner: sys::Once,