From d1b28b75d25d5f4c3d1769822a1b106b95b106f1 Mon Sep 17 00:00:00 2001 From: Trevor Gross Date: Mon, 12 Dec 2022 04:16:18 -0500 Subject: [PATCH] Documentation updates to better share the purpose of OnceCell/OnceLock --- library/core/src/cell.rs | 93 +++++++++++++++++++++++++---------- library/core/src/cell/once.rs | 6 ++- library/std/src/sync/mod.rs | 5 +- 3 files changed, 76 insertions(+), 28 deletions(-) diff --git a/library/core/src/cell.rs b/library/core/src/cell.rs index 178927f6385..d378b0b3b97 100644 --- a/library/core/src/cell.rs +++ b/library/core/src/cell.rs @@ -11,36 +11,77 @@ //! mutate it. //! //! Shareable mutable containers exist to permit mutability in a controlled manner, even in the -//! presence of aliasing. Both [`Cell`] and [`RefCell`] allow doing this in a single-threaded -//! way. However, neither `Cell` nor `RefCell` are thread safe (they do not implement -//! [`Sync`]). If you need to do aliasing and mutation between multiple threads it is possible to -//! use [`Mutex`], [`RwLock`] or [`atomic`] types. +//! presence of aliasing. [`Cell`], [`RefCell`], and [`OnceCell`] allow doing this in +//! a single-threaded way - they do not implement [`Sync`]. (If you need to do aliasing and +//! mutation among multiple threads, [`Mutex`], [`RwLock`], [`OnceLock`] or [`atomic`] +//! types are the correct data structures to do so). //! -//! Values of the `Cell` and `RefCell` types may be mutated through shared references (i.e. -//! the common `&T` type), whereas most Rust types can only be mutated through unique (`&mut T`) -//! references. We say that `Cell` and `RefCell` provide 'interior mutability', in contrast -//! with typical Rust types that exhibit 'inherited mutability'. +//! Values of the `Cell`, `RefCell`, and `OnceCell` types may be mutated through shared +//! references (i.e. the common `&T` type), whereas most Rust types can only be mutated through +//! unique (`&mut T`) references. We say these cell types provide 'interior mutability' +//! (mutable via `&T`), in contrast with typical Rust types that exhibit 'inherited mutability' +//! (mutable only via `&mut T`). //! -//! Cell types come in two flavors: `Cell` and `RefCell`. `Cell` implements interior -//! mutability by moving values in and out of the `Cell`. To use references instead of values, -//! one must use the `RefCell` type, acquiring a write lock before mutating. `Cell` provides -//! methods to retrieve and change the current interior value: +//! Cell types come in three flavors: `Cell`, `RefCell`, and `OnceCell`. Each provides +//! a different way of providing safe interior mutability. +//! +//! ## `Cell` +//! +//! [`Cell`] implements interior mutability by moving values in and out of the cell. That is, an +//! `&mut T` to the inner value can never be obtained, and the value itself cannot be directly +//! obtained without replacing it with something else. Both of these rules ensure that there is +//! never more than one reference pointing to the inner value. This type provides the following +//! methods: //! //! - For types that implement [`Copy`], the [`get`](Cell::get) method retrieves the current -//! interior value. +//! interior value by duplicating it. //! - For types that implement [`Default`], the [`take`](Cell::take) method replaces the current //! interior value with [`Default::default()`] and returns the replaced value. -//! - For all types, the [`replace`](Cell::replace) method replaces the current interior value and -//! returns the replaced value and the [`into_inner`](Cell::into_inner) method consumes the -//! `Cell` and returns the interior value. Additionally, the [`set`](Cell::set) method -//! replaces the interior value, dropping the replaced value. +//! - All types have: +//! - [`replace`](Cell::replace): replaces the current interior value and returns the replaced +//! value. +//! - [`into_inner`](Cell::into_inner): this method consumes the `Cell` and returns the +//! interior value. +//! - [`set`](Cell::set): this method replaces the interior value, dropping the replaced value. //! -//! `RefCell` uses Rust's lifetimes to implement 'dynamic borrowing', a process whereby one can +//! `Cell` is typically used for more simple types where copying or moving values isn't too +//! resource intensive (e.g. numbers), and should usually be preferred over other cell types when +//! possible. For larger and non-copy types, `RefCell` provides some advantages. +//! +//! ## `RefCell` +//! +//! [`RefCell`] uses Rust's lifetimes to implement "dynamic borrowing", a process whereby one can //! claim temporary, exclusive, mutable access to the inner value. Borrows for `RefCell`s are -//! tracked 'at runtime', unlike Rust's native reference types which are entirely tracked -//! statically, at compile time. Because `RefCell` borrows are dynamic it is possible to attempt -//! to borrow a value that is already mutably borrowed; when this happens it results in thread -//! panic. +//! tracked at _runtime_, unlike Rust's native reference types which are entirely tracked +//! statically, at compile time. +//! +//! An immutable reference to a `RefCell`'s inner value (`&T`) can be obtained with +//! [`borrow`](`RefCell::borrow`), and a mutable borrow (`&mut T`) can be obtained with +//! [`borrow_mut`](`RefCell::borrow_mut`). When these functions are called, they first verify that +//! Rust's borrow rules will be satisfied: any number of immutable borrows are allowed or a +//! single immutable borrow is allowed, but never both. If a borrow is attempted that would violate +//! these rules, the thread will panic. +//! +//! The corresponding [`Sync`] version of `RefCell` is [`RwLock`]. +//! +//! ## `OnceCell` +//! +//! [`OnceCell`] is somewhat of a hybrid of `Cell` and `RefCell` that works for values that +//! typically only need to be set once. This means that a reference `&T` can be obtained without +//! moving or copying the inner value (unlike `Cell`) but also without runtime checks (unlike +//! `RefCell`). However, its value can also not be updated once set unless you have a mutable +//! reference to the `OnceCell`. +//! +//! `OnceCell` provides the following methods: +//! +//! - [`get`](OnceCell::get): obtain a reference to the inner value +//! - [`set`](OnceCell::set): set the inner value if it is unset (returns a `Result`) +//! - [`get_or_init`](OnceCell::get_or_init): return the inner value, initializing it if needed +//! - [`get_mut`](OnceCell::get_mut): provide a mutable reference to the inner value, only available +//! if you have a mutable reference to the cell itself. +//! +//! The corresponding [`Sync`] version of `OnceCell` is [`OnceLock`]. +//! //! //! # When to choose interior mutability //! @@ -188,6 +229,8 @@ //! [`Rc`]: ../../std/rc/struct.Rc.html //! [`RwLock`]: ../../std/sync/struct.RwLock.html //! [`Mutex`]: ../../std/sync/struct.Mutex.html +//! [`OnceLock`]: ../../std/sync/struct.OnceLock.html +//! [`Sync`]: ../../std/marker/trait.Sync.html //! [`atomic`]: crate::sync::atomic #![stable(feature = "rust1", since = "1.0.0")] @@ -419,7 +462,7 @@ impl Cell { mem::replace(unsafe { &mut *self.value.get() }, val) } - /// Unwraps the value. + /// Unwraps the value, consuming the cell. /// /// # Examples /// @@ -1969,7 +2012,7 @@ impl UnsafeCell { UnsafeCell { value } } - /// Unwraps the value. + /// Unwraps the value, consuming the cell. /// /// # Examples /// @@ -2133,7 +2176,7 @@ impl SyncUnsafeCell { Self { value: UnsafeCell { value } } } - /// Unwraps the value. + /// Unwraps the value, consuming the cell. #[inline] pub const fn into_inner(self) -> T { self.value.into_inner() diff --git a/library/core/src/cell/once.rs b/library/core/src/cell/once.rs index c5bd7a5fa01..5dc2d523198 100644 --- a/library/core/src/cell/once.rs +++ b/library/core/src/cell/once.rs @@ -4,8 +4,10 @@ use crate::mem; /// A cell which can be written to only once. /// -/// Unlike [`RefCell`], a `OnceCell` only provides shared `&T` references to its value. -/// Unlike [`Cell`], a `OnceCell` doesn't require copying or replacing the value to access it. +/// 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. /// /// For a thread-safe version of this struct, see [`std::sync::OnceLock`]. /// diff --git a/library/std/src/sync/mod.rs b/library/std/src/sync/mod.rs index 5dd585b9b37..19641753ffe 100644 --- a/library/std/src/sync/mod.rs +++ b/library/std/src/sync/mod.rs @@ -133,7 +133,9 @@ //! - [`Mutex`]: Mutual Exclusion mechanism, which ensures that at //! most one thread at a time is able to access some data. //! -//! - [`Once`]: Used for thread-safe, one-time initialization of a +//! - [`Once`]: Used for a thread-safe, one-time global initialization routine +//! +//! - [`OnceLock`]: Used for thread-safe, one-time initialization of a //! global variable. //! //! - [`RwLock`]: Provides a mutual exclusion mechanism which allows @@ -147,6 +149,7 @@ //! [`mpsc`]: crate::sync::mpsc //! [`Mutex`]: crate::sync::Mutex //! [`Once`]: crate::sync::Once +//! [`OnceLock`]: crate::sync::OnceLock //! [`RwLock`]: crate::sync::RwLock #![stable(feature = "rust1", since = "1.0.0")]