From 1376c5a617be5c25655d0d7cb63e3beaa5a6e026 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Wed, 17 Apr 2024 14:20:39 +0200 Subject: Merging upstream version 1.70.0+dfsg1. Signed-off-by: Daniel Baumann --- library/core/src/cell.rs | 105 ++++++++++++++++++++++++++++++++++------------- 1 file changed, 77 insertions(+), 28 deletions(-) (limited to 'library/core/src/cell.rs') diff --git a/library/core/src/cell.rs b/library/core/src/cell.rs index 897d03595..33d928e23 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. +//! +//! `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 +//! [`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")] @@ -202,13 +245,19 @@ use crate::ptr::{self, NonNull}; mod lazy; mod once; -#[unstable(feature = "once_cell", issue = "74465")] +#[unstable(feature = "lazy_cell", issue = "109736")] pub use lazy::LazyCell; -#[unstable(feature = "once_cell", issue = "74465")] +#[stable(feature = "once_cell", since = "1.70.0")] pub use once::OnceCell; /// A mutable memory location. /// +/// # Memory layout +/// +/// `Cell` has the same [memory layout and caveats as +/// `UnsafeCell`](UnsafeCell#memory-layout). In particular, this means that +/// `Cell` has the same in-memory representation as its inner type `T`. +/// /// # Examples /// /// In this example, you can see that `Cell` enables mutation inside an @@ -413,7 +462,7 @@ impl Cell { mem::replace(unsafe { &mut *self.value.get() }, val) } - /// Unwraps the value. + /// Unwraps the value, consuming the cell. /// /// # Examples /// @@ -1767,7 +1816,7 @@ impl fmt::Display for RefMut<'_, T> { /// `UnsafeCell` opts-out of the immutability guarantee for `&T`: a shared reference /// `&UnsafeCell` may point to data that is being mutated. This is called "interior mutability". /// -/// All other types that allow internal mutability, such as `Cell` and `RefCell`, internally +/// All other types that allow internal mutability, such as [`Cell`] and [`RefCell`], internally /// use `UnsafeCell` to wrap their data. /// /// Note that only the immutability guarantee for shared references is affected by `UnsafeCell`. The @@ -1963,7 +2012,7 @@ impl UnsafeCell { UnsafeCell { value } } - /// Unwraps the value. + /// Unwraps the value, consuming the cell. /// /// # Examples /// @@ -2127,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() -- cgit v1.2.3