Rollup merge of #140715 - lukaslueg:oncecellsyncdocs, r=tgross35

Clarify &mut-methods' docs on sync::OnceLock

Three small changes to the docs of `sync::OnceLock`:

* The docs for `OnceLock::take()` used to [say](https://doc.rust-lang.org/std/sync/struct.OnceLock.html#method.take) "**Safety** is guaranteed by requiring a mutable reference." (emphasis mine). While technically correct, imho its not necessary to even mention safety - as opposed to unsafety - here: Safety never comes up wrt `OnceLock`, as there is (currently) no way to interact with a `OnceLock` in an unsafe way; there are no unsafe methods on `OnceLock`, so there is "safety" guarantee required anywhere. What we simply meant to say is "**Synchronization** is guaranteed...".
* I've add that phrase to the other methods of `OnceLock` which take a `&mut self`, to highlight the fact that having a `&mut OnceLock` guarantees that synchronization with other threads is not required. This is the same as with [`Mutex::get_mut()`](https://doc.rust-lang.org/std/sync/struct.Mutex.html#method.get_mut), [`Cell::get_mut()`](https://doc.rust-lang.org/std/cell/struct.Cell.html#method.get_mut), and others.
* In that spirit, the half-sentence "or being initialized" was removed from `get_mut()`, as there is no way that the `OnceLock` is being initialized while we are holding `&mut` to it. Probably a copy&paste from `.get()`

1 files changed, 13 insertions, 5 deletions

diff --git a/library/std/src/sync/once_lock.rs b/library/std/src/sync/once_lock.rs
index 324b5451873..a5c3a6c46a4 100644
--- a/library/std/src/sync/once_lock.rs
+++ b/library/std/src/sync/once_lock.rs
@@ -159,8 +159,11 @@ impl<T> OnceLock<T> {
 
     /// Gets the mutable reference to the underlying value.
     ///
-    /// Returns `None` if the cell is uninitialized, or being initialized.
-    /// This method never blocks.
+    /// Returns `None` if the cell is uninitialized.
+    ///
+    /// This method never blocks. Since it borrows the `OnceLock` mutably,
+    /// it is statically guaranteed that no active borrows to the `OnceLock`
+    /// exist, including from other threads.
     #[inline]
     #[stable(feature = "once_cell", since = "1.70.0")]
     pub fn get_mut(&mut self) -> Option<&mut T> {
@@ -315,7 +318,9 @@ impl<T> OnceLock<T> {
     /// Gets the mutable reference of the contents of the cell, initializing
     /// it to `f()` if the cell was uninitialized.
     ///
-    /// This method never blocks.
+    /// This method never blocks. Since it borrows the `OnceLock` mutably,
+    /// it is statically guaranteed that no active borrows to the `OnceLock`
+    /// exist, including from other threads.
     ///
     /// # Panics
     ///
@@ -405,7 +410,9 @@ impl<T> OnceLock<T> {
     /// it to `f()` if the cell was uninitialized. If the cell was uninitialized
     /// and `f()` failed, an error is returned.
     ///
-    /// This method never blocks.
+    /// This method never blocks. Since it borrows the `OnceLock` mutably,
+    /// it is statically guaranteed that no active borrows to the `OnceLock`
+    /// exist, including from other threads.
     ///
     /// # Panics
     ///
@@ -469,7 +476,8 @@ impl<T> OnceLock<T> {
     ///
     /// Has no effect and returns `None` if the `OnceLock` was uninitialized.
     ///
-    /// Safety is guaranteed by requiring a mutable reference.
+    /// Since this method borrows the `OnceLock` mutably, it is statically guaranteed that
+    /// no active borrows to the `OnceLock` exist, including from other threads.
     ///
     /// # Examples
     ///