bjoernager/rust
bjoernager/rust
1
Fork 0
Code Activity

Rollup merge of #136289 - Pyr0de:oncecell-docs, r=tgross35

Browse source 
OnceCell & OnceLock docs: Using (un)initialized consistently

Changed
* `set` / `initialize` / `full` to `initialized state`
* `uninitialize` / `empty` to `uninitialized state`
* `f` to `f()`
* Added explaination of `uninitialized state` & `initialized state`

[OnceCell Docs](https://doc.rust-lang.org/nightly/std/cell/struct.OnceCell.html)
[OnceLock Docs](https://doc.rust-lang.org/nightly/std/sync/struct.OnceLock.html)

Fixes #85716
``@rustbot`` label +A-docs
This commit is contained in:
Matthias Krüger 2025-02-03 21:11:33 +01:00 • committed by GitHub
commit f2b7a299d2
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
2 changed files with 64 additions and 54 deletions
Download patch file Download diff file Expand all files Collapse all files

53
library/core/src/cell/once.rs
View file

@ -8,6 +8,9 @@ use crate::{fmt, mem};
/// only immutable references can be obtained unless one has a mutable reference to the cell
/// itself. In the same vein, the cell can only be re-initialized with such a mutable reference.
///
/// A `OnceCell` can be thought of as a safe abstraction over uninitialized data that becomes
/// initialized once written.
///
/// For a thread-safe version of this struct, see [`std::sync::OnceLock`].
///
/// [`RefCell`]: crate::cell::RefCell
@ -35,7 +38,7 @@ pub struct OnceCell<T> {
}
impl<T> OnceCell<T> {
/// Creates a new empty cell.
/// Creates a new uninitialized cell.
#[inline]
#[must_use]
#[stable(feature = "once_cell", since = "1.70.0")]
@ -46,7 +49,7 @@ impl<T> OnceCell<T> {
/// Gets the reference to the underlying value.
///
/// Returns `None` if the cell is empty.
/// Returns `None` if the cell is uninitialized.
#[inline]
#[stable(feature = "once_cell", since = "1.70.0")]
pub fn get(&self) -> Option<&T> {
@ -56,19 +59,19 @@ impl<T> OnceCell<T> {
/// Gets the mutable reference to the underlying value.
///
/// Returns `None` if the cell is empty.
/// Returns `None` if the cell is uninitialized.
#[inline]
#[stable(feature = "once_cell", since = "1.70.0")]
pub fn get_mut(&mut self) -> Option<&mut T> {
self.inner.get_mut().as_mut()
}
/// Sets the contents of the cell to `value`.
/// Initializes the contents of the cell to `value`.
///
/// # Errors
///
/// This method returns `Ok(())` if the cell was empty and `Err(value)` if
/// it was full.
/// This method returns `Ok(())` if the cell was uninitialized
/// and `Err(value)` if it was already initialized.
///
/// # Examples
///
@ -92,13 +95,13 @@ impl<T> OnceCell<T> {
}
}
/// Sets the contents of the cell to `value` if the cell was empty, then
/// returns a reference to it.
/// Initializes the contents of the cell to `value` if the cell was
/// uninitialized, then returns a reference to it.
///
/// # Errors
///
/// This method returns `Ok(&value)` if the cell was empty and
/// `Err(&current_value, value)` if it was full.
/// This method returns `Ok(&value)` if the cell was uninitialized
/// and `Err((&current_value, value))` if it was already initialized.
///
/// # Examples
///
@ -130,12 +133,12 @@ impl<T> OnceCell<T> {
Ok(slot.insert(value))
}
/// Gets the contents of the cell, initializing it with `f`
/// if the cell was empty.
/// Gets the contents of the cell, initializing it to `f()`
/// if the cell was uninitialized.
///
/// # Panics
///
/// If `f` panics, the panic is propagated to the caller, and the cell
/// If `f()` panics, the panic is propagated to the caller, and the cell
/// remains uninitialized.
///
/// It is an error to reentrantly initialize the cell from `f`. Doing
@ -164,11 +167,11 @@ impl<T> OnceCell<T> {
}
/// Gets the mutable reference of the contents of the cell,
/// initializing it with `f` if the cell was empty.
/// initializing it to `f()` if the cell was uninitialized.
///
/// # Panics
///
/// If `f` panics, the panic is propagated to the caller, and the cell
/// If `f()` panics, the panic is propagated to the caller, and the cell
/// remains uninitialized.
///
/// # Examples
@ -199,13 +202,13 @@ impl<T> OnceCell<T> {
}
}
/// Gets the contents of the cell, initializing it with `f` if
/// the cell was empty. If the cell was empty and `f` failed, an
/// error is returned.
/// Gets the contents of the cell, initializing it to `f()` if
/// the cell was uninitialized. If the cell was uninitialized
/// and `f()` failed, an error is returned.
///
/// # Panics
///
/// If `f` panics, the panic is propagated to the caller, and the cell
/// If `f()` panics, the panic is propagated to the caller, and the cell
/// remains uninitialized.
///
/// It is an error to reentrantly initialize the cell from `f`. Doing
@ -239,12 +242,12 @@ impl<T> OnceCell<T> {
}
/// Gets the mutable reference of the contents of the cell, initializing
/// it with `f` if the cell was empty. If the cell was empty and `f` failed,
/// an error is returned.
/// it to `f()` if the cell was uninitialized. If the cell was uninitialized
/// and `f()` failed, an error is returned.
///
/// # Panics
///
/// If `f` panics, the panic is propagated to the caller, and the cell
/// If `f()` panics, the panic is propagated to the caller, and the cell
/// remains uninitialized.
///
/// # Examples
@ -256,7 +259,7 @@ impl<T> OnceCell<T> {
///
/// let mut cell: OnceCell<u32> = OnceCell::new();
///
/// // Failed initializers do not change the value
/// // Failed attempts to initialize the cell do not change its contents
/// assert!(cell.get_mut_or_try_init(|| "not a number!".parse()).is_err());
/// assert!(cell.get().is_none());
///
@ -295,7 +298,7 @@ impl<T> OnceCell<T> {
/// Consumes the cell, returning the wrapped value.
///
/// Returns `None` if the cell was empty.
/// Returns `None` if the cell was uninitialized.
///
/// # Examples
///
@ -321,7 +324,7 @@ impl<T> OnceCell<T> {
/// Takes the value out of this `OnceCell`, moving it back to an uninitialized state.
///
/// Has no effect and returns `None` if the `OnceCell` hasn't been initialized.
/// Has no effect and returns `None` if the `OnceCell` is uninitialized.
///
/// Safety is guaranteed by requiring a mutable reference.
///

65
library/std/src/sync/once_lock.rs
View file

@ -13,6 +13,9 @@ use crate::sync::Once;
/// Where OnceLock shines is when LazyLock is too simple to support a given case, as LazyLock
/// doesn't allow additional inputs to its function after you call [`LazyLock::new(|| ...)`].
///
/// A `OnceLock` can be thought of as a safe abstraction over uninitialized data that becomes
/// initialized once written.
///
/// [`OnceCell`]: crate::cell::OnceCell
/// [`LazyLock<T, F>`]: crate::sync::LazyLock
/// [`LazyLock::new(|| ...)`]: crate::sync::LazyLock::new
@ -126,7 +129,7 @@ pub struct OnceLock<T> {
}
impl<T> OnceLock<T> {
/// Creates a new empty cell.
/// Creates a new uninitialized cell.
#[inline]
#[must_use]
#[stable(feature = "once_cell", since = "1.70.0")]
@ -141,8 +144,8 @@ impl<T> OnceLock<T> {
/// Gets the reference to the underlying value.
///
/// Returns `None` if the cell is empty, or being initialized. This
/// method never blocks.
/// Returns `None` if the cell is uninitialized, or being initialized.
/// This method never blocks.
#[inline]
#[stable(feature = "once_cell", since = "1.70.0")]
pub fn get(&self) -> Option<&T> {
@ -156,7 +159,8 @@ impl<T> OnceLock<T> {
/// Gets the mutable reference to the underlying value.
///
/// Returns `None` if the cell is empty. This method never blocks.
/// Returns `None` if the cell is uninitialized, or being initialized.
/// This method never blocks.
#[inline]
#[stable(feature = "once_cell", since = "1.70.0")]
pub fn get_mut(&mut self) -> Option<&mut T> {
@ -194,12 +198,13 @@ impl<T> OnceLock<T> {
unsafe { self.get_unchecked() }
}
/// Sets the contents of this cell to `value`.
/// Initializes the contents of the cell to `value`.
///
/// May block if another thread is currently attempting to initialize the cell. The cell is
/// guaranteed to contain a value when set returns, though not necessarily the one provided.
/// guaranteed to contain a value when `set` returns, though not necessarily the one provided.
///
/// Returns `Ok(())` if the cell's value was set by this call.
/// Returns `Ok(())` if the cell was uninitialized and
/// `Err(value)` if the cell was already initialized.
///
/// # Examples
///
@ -228,13 +233,15 @@ impl<T> OnceLock<T> {
}
}
/// Sets the contents of this cell to `value` if the cell was empty, then
/// returns a reference to it.
/// Initializes the contents of the cell to `value` if the cell was uninitialized,
/// then returns a reference to it.
///
/// May block if another thread is currently attempting to initialize the cell. The cell is
/// guaranteed to contain a value when set returns, though not necessarily the one provided.
/// guaranteed to contain a value when `try_insert` returns, though not necessarily the
/// one provided.
///
/// Returns `Ok(&value)` if the cell was empty and `Err(&current_value, value)` if it was full.
/// Returns `Ok(&value)` if the cell was uninitialized and
/// `Err((&current_value, value))` if it was already initialized.
///
/// # Examples
///
@ -267,8 +274,8 @@ impl<T> OnceLock<T> {
}
}
/// Gets the contents of the cell, initializing it with `f` if the cell
/// was empty.
/// Gets the contents of the cell, initializing it to `f()` if the cell
/// was uninitialized.
///
/// Many threads may call `get_or_init` concurrently with different
/// initializing functions, but it is guaranteed that only one function
@ -276,7 +283,7 @@ impl<T> OnceLock<T> {
///
/// # Panics
///
/// If `f` panics, the panic is propagated to the caller, and the cell
/// If `f()` panics, the panic is propagated to the caller, and the cell
/// remains uninitialized.
///
/// It is an error to reentrantly initialize the cell from `f`. The
@ -306,13 +313,13 @@ impl<T> OnceLock<T> {
}
/// Gets the mutable reference of the contents of the cell, initializing
/// it with `f` if the cell was empty.
/// it to `f()` if the cell was uninitialized.
///
/// This method never blocks.
///
/// # Panics
///
/// If `f` panics, the panic is propagated to the caller, and the cell
/// If `f()` panics, the panic is propagated to the caller, and the cell
/// remains uninitialized.
///
/// # Examples
@ -343,13 +350,13 @@ impl<T> OnceLock<T> {
}
}
/// Gets the contents of the cell, initializing it with `f` if
/// the cell was empty. If the cell was empty and `f` failed, an
/// error is returned.
/// Gets the contents of the cell, initializing it to `f()` if
/// the cell was uninitialized. If the cell was uninitialized
/// and `f()` failed, an error is returned.
///
/// # Panics
///
/// If `f` panics, the panic is propagated to the caller, and
/// If `f()` panics, the panic is propagated to the caller, and
/// the cell remains uninitialized.
///
/// It is an error to reentrantly initialize the cell from `f`.
@ -395,14 +402,14 @@ impl<T> OnceLock<T> {
}
/// Gets the mutable reference of the contents of the cell, initializing
/// it with `f` if the cell was empty. If the cell was empty and `f` failed,
/// an error is returned.
/// it to `f()` if the cell was uninitialized. If the cell was uninitialized
/// and `f()` failed, an error is returned.
///
/// This method never blocks.
///
/// # Panics
///
/// If `f` panics, the panic is propagated to the caller, and
/// If `f()` panics, the panic is propagated to the caller, and
/// the cell remains uninitialized.
///
/// # Examples
@ -414,7 +421,7 @@ impl<T> OnceLock<T> {
///
/// let mut cell: OnceLock<u32> = OnceLock::new();
///
/// // Failed initializers do not change the value
/// // Failed attempts to initialize the cell do not change its contents
/// assert!(cell.get_mut_or_try_init(|| "not a number!".parse()).is_err());
/// assert!(cell.get().is_none());
///
@ -438,7 +445,7 @@ impl<T> OnceLock<T> {
}
/// Consumes the `OnceLock`, returning the wrapped value. Returns
/// `None` if the cell was empty.
/// `None` if the cell was uninitialized.
///
/// # Examples
///
@ -460,7 +467,7 @@ impl<T> OnceLock<T> {
/// Takes the value out of this `OnceLock`, moving it back to an uninitialized state.
///
/// Has no effect and returns `None` if the `OnceLock` hasn't been initialized.
/// Has no effect and returns `None` if the `OnceLock` was uninitialized.
///
/// Safety is guaranteed by requiring a mutable reference.
///
@ -526,7 +533,7 @@ impl<T> OnceLock<T> {
/// # Safety
///
/// The value must be initialized
/// The cell must be initialized
#[inline]
unsafe fn get_unchecked(&self) -> &T {
debug_assert!(self.is_initialized());
@ -535,7 +542,7 @@ impl<T> OnceLock<T> {
/// # Safety
///
/// The value must be initialized
/// The cell must be initialized
#[inline]
unsafe fn get_unchecked_mut(&mut self) -> &mut T {
debug_assert!(self.is_initialized());
@ -560,7 +567,7 @@ impl<T: UnwindSafe> UnwindSafe for OnceLock<T> {}
#[stable(feature = "once_cell", since = "1.70.0")]
impl<T> Default for OnceLock<T> {
/// Creates a new empty cell.
/// Creates a new uninitialized cell.
///
/// # Example
///