Skip to content

Commit

Permalink
Unrolled build for rust-lang#125504
Browse files Browse the repository at this point in the history
Rollup merge of rust-lang#125504 - mqudsi:once_nominal, r=cuviper

Change pedantically incorrect OnceCell/OnceLock wording

While the semantic intent of a OnceCell/OnceLock is that it can only be written to once (upon init), the fact of the matter is that both these types offer a `take(&mut self) -> Option<T>` mechanism that, when successful, resets the cell to its initial state, thereby [technically allowing it to be written to again](https://play.rust-lang.org/?version=stable&mode=debug&edition=2021&gist=415c023a6ae1ef35f371a2d3bb1aa735)

Despite the fact that this can only happen with a mutable reference (generally only used during the construction of the OnceCell/OnceLock), it would be incorrect to say that the type itself as a whole *categorically* prevents being initialized or written to more than once (since it is possible to imagine an identical type only without the `take()` method that actually fulfills that contract).

To clarify, change "that cannot be.." to "that nominally cannot.." and add a note to OnceCell about what can be done with an `&mut Self` reference.

```@rustbot``` label +A-rustdocs
  • Loading branch information
rust-timer committed Jun 4, 2024
2 parents 27529d5 + 65dffc1 commit e7cfec2
Show file tree
Hide file tree
Showing 2 changed files with 3 additions and 3 deletions.
4 changes: 2 additions & 2 deletions library/core/src/cell/once.rs
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,12 @@ use crate::cell::UnsafeCell;
use crate::fmt;
use crate::mem;

/// A cell which can be written to only once.
/// A cell which can nominally be written to only once.
///
/// This allows obtaining a shared `&T` reference to its inner value without copying or replacing
/// it (unlike [`Cell`]), and without runtime borrow checks (unlike [`RefCell`]). However,
/// only immutable references can be obtained unless one has a mutable reference to the cell
/// itself.
/// itself. In the same vein, the cell can only be re-initialized with such a mutable reference.
///
/// For a thread-safe version of this struct, see [`std::sync::OnceLock`].
///
Expand Down
2 changes: 1 addition & 1 deletion library/std/src/sync/once_lock.rs
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ use crate::mem::MaybeUninit;
use crate::panic::{RefUnwindSafe, UnwindSafe};
use crate::sync::Once;

/// A synchronization primitive which can be written to only once.
/// A synchronization primitive which can nominally be written to only once.
///
/// This type is a thread-safe [`OnceCell`], and can be used in statics.
///
Expand Down

0 comments on commit e7cfec2

Please sign in to comment.