about summary refs log tree commit diff
diff options
context:
space:
mode:
authorMatthias Krüger <matthias.krueger@famsik.de>2024-06-15 10:56:44 +0200
committerGitHub <noreply@github.com>2024-06-15 10:56:44 +0200
commit83cbceac0f4646967c61419c324dcd4e535b511d (patch)
tree18902e510bd2e8f7494eab6c242d240c19d2d9a5
parente287a000181d3f27e4dd41551fe111ba9f1e68df (diff)
parentb8eb6ad03273d42d6a22ced57a46e5652fb35f1d (diff)
Rollup merge of #126509 - workingjubilee:gently-discourage-doing-things-once, r=jhpratt
std: suggest OnceLock over Once

It was noted in https://github.com/rust-lang/rust/issues/125615#issuecomment-2149590818 that Once is not necessary in most cases and should be discouraged. Once is really just an implementation detail of OnceLock that others can use if they want. Suggest they use OnceLock instead.
-rw-r--r--library/std/src/sync/mod.rs3
-rw-r--r--library/std/src/sync/once.rs15
2 files changed, 14 insertions, 4 deletions
diff --git a/library/std/src/sync/mod.rs b/library/std/src/sync/mod.rs
index 2a13b1a8ae2..9a38c42f43a 100644
--- a/library/std/src/sync/mod.rs
+++ b/library/std/src/sync/mod.rs
@@ -133,7 +133,8 @@
 //! - [`Mutex`]: Mutual Exclusion mechanism, which ensures that at
 //!   most one thread at a time is able to access some data.
 //!
-//! - [`Once`]: Used for a thread-safe, one-time global initialization routine
+//! - [`Once`]: Used for a thread-safe, one-time global initialization routine.
+//!   Mostly useful for implementing other types like `OnceLock`.
 //!
 //! - [`OnceLock`]: Used for thread-safe, one-time initialization of a
 //!   variable, with potentially different initializers based on the caller.
diff --git a/library/std/src/sync/once.rs b/library/std/src/sync/once.rs
index 608229fd674..9d969af8c6d 100644
--- a/library/std/src/sync/once.rs
+++ b/library/std/src/sync/once.rs
@@ -10,9 +10,15 @@ use crate::fmt;
 use crate::panic::{RefUnwindSafe, UnwindSafe};
 use crate::sys::sync as sys;
 
-/// 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()`].
+/// A low-level synchronization primitive for one-time global execution.
+///
+/// Previously this was the only "execute once" synchronization in `std`.
+/// Other libraries implemented novel synchronizing types with `Once`, like
+/// [`OnceLock<T>`] or [`LazyLock<T, F>`], before those were added to `std`.
+/// `OnceLock<T>` in particular supersedes `Once` in functionality and should
+/// be preferred for the common case where the `Once` is associated with data.
+///
+/// This type can only be constructed with [`Once::new()`].
 ///
 /// # Examples
 ///
@@ -25,6 +31,9 @@ use crate::sys::sync as sys;
 ///     // run initialization here
 /// });
 /// ```
+///
+/// [`OnceLock<T>`]: crate::sync::OnceLock
+/// [`LazyLock<T, F>`]: crate::sync::LazyLock
 #[stable(feature = "rust1", since = "1.0.0")]
 pub struct Once {
     inner: sys::Once,