|
|
|
@ -11,12 +11,10 @@
|
|
|
|
|
//! mutate it.
|
|
|
|
|
//!
|
|
|
|
|
//! Shareable mutable containers exist to permit mutability in a controlled manner, even in the
|
|
|
|
|
//! presence of aliasing. Both `Cell<T>` and `RefCell<T>` allow doing this in a single-threaded
|
|
|
|
|
//! presence of aliasing. Both [`Cell<T>`] and [`RefCell<T>`] allow doing this in a single-threaded
|
|
|
|
|
//! way. However, neither `Cell<T>` nor `RefCell<T>` 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`](../../std/sync/struct.Mutex.html),
|
|
|
|
|
//! [`RwLock`](../../std/sync/struct.RwLock.html) or
|
|
|
|
|
//! [`atomic`](../../core/sync/atomic/index.html) types.
|
|
|
|
|
//! [`Sync`]). If you need to do aliasing and mutation between multiple threads it is possible to
|
|
|
|
|
//! use [`Mutex<T>`], [`RwLock<T>`] or [`atomic`] types.
|
|
|
|
|
//!
|
|
|
|
|
//! Values of the `Cell<T>` and `RefCell<T>` 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`)
|
|
|
|
@ -28,13 +26,14 @@
|
|
|
|
|
//! one must use the `RefCell<T>` type, acquiring a write lock before mutating. `Cell<T>` provides
|
|
|
|
|
//! methods to retrieve and change the current interior value:
|
|
|
|
|
//!
|
|
|
|
|
//! - For types that implement `Copy`, the `get` method retrieves the current interior value.
|
|
|
|
|
//! - For types that implement `Default`, the `take` method replaces the current interior value
|
|
|
|
|
//! with `Default::default()` and returns the replaced value.
|
|
|
|
|
//! - For all types, the `replace` method replaces the current interior value and returns the
|
|
|
|
|
//! replaced value and the `into_inner` method consumes the `Cell<T>` and returns the interior
|
|
|
|
|
//! value. Additionally, the `set` method replaces the interior value, dropping the replaced
|
|
|
|
|
//! value.
|
|
|
|
|
//! - For types that implement [`Copy`], the [`get`](Cell::get) method retrieves the current
|
|
|
|
|
//! interior value.
|
|
|
|
|
//! - 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<T>` and returns the interior value. Additionally, the [`set`](Cell::set) method
|
|
|
|
|
//! replaces the interior value, dropping the replaced value.
|
|
|
|
|
//!
|
|
|
|
|
//! `RefCell<T>` 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<T>`s are
|
|
|
|
@ -54,12 +53,12 @@
|
|
|
|
|
//!
|
|
|
|
|
//! * Introducing mutability 'inside' of something immutable
|
|
|
|
|
//! * Implementation details of logically-immutable methods.
|
|
|
|
|
//! * Mutating implementations of `Clone`.
|
|
|
|
|
//! * Mutating implementations of [`Clone`].
|
|
|
|
|
//!
|
|
|
|
|
//! ## Introducing mutability 'inside' of something immutable
|
|
|
|
|
//!
|
|
|
|
|
//! Many shared smart pointer types, including `Rc<T>` and `Arc<T>`, provide containers that can be
|
|
|
|
|
//! cloned and shared between multiple parties. Because the contained values may be
|
|
|
|
|
//! Many shared smart pointer types, including [`Rc<T>`] and [`Arc<T>`], provide containers that can
|
|
|
|
|
//! be cloned and shared between multiple parties. Because the contained values may be
|
|
|
|
|
//! multiply-aliased, they can only be borrowed with `&`, not `&mut`. Without cells it would be
|
|
|
|
|
//! impossible to mutate data inside of these smart pointers at all.
|
|
|
|
|
//!
|
|
|
|
@ -91,7 +90,7 @@
|
|
|
|
|
//! ```
|
|
|
|
|
//!
|
|
|
|
|
//! Note that this example uses `Rc<T>` and not `Arc<T>`. `RefCell<T>`s are for single-threaded
|
|
|
|
|
//! scenarios. Consider using `RwLock<T>` or `Mutex<T>` if you need shared mutability in a
|
|
|
|
|
//! scenarios. Consider using [`RwLock<T>`] or [`Mutex<T>`] if you need shared mutability in a
|
|
|
|
|
//! multi-threaded situation.
|
|
|
|
|
//!
|
|
|
|
|
//! ## Implementation details of logically-immutable methods
|
|
|
|
@ -127,10 +126,10 @@
|
|
|
|
|
//! ## Mutating implementations of `Clone`
|
|
|
|
|
//!
|
|
|
|
|
//! This is simply a special - but common - case of the previous: hiding mutability for operations
|
|
|
|
|
//! that appear to be immutable. The `clone` method is expected to not change the source value, and
|
|
|
|
|
//! is declared to take `&self`, not `&mut self`. Therefore, any mutation that happens in the
|
|
|
|
|
//! `clone` method must use cell types. For example, `Rc<T>` maintains its reference counts within a
|
|
|
|
|
//! `Cell<T>`.
|
|
|
|
|
//! that appear to be immutable. The [`clone`](Clone::clone) method is expected to not change the
|
|
|
|
|
//! source value, and is declared to take `&self`, not `&mut self`. Therefore, any mutation that
|
|
|
|
|
//! happens in the `clone` method must use cell types. For example, [`Rc<T>`] maintains its
|
|
|
|
|
//! reference counts within a `Cell<T>`.
|
|
|
|
|
//!
|
|
|
|
|
//! ```
|
|
|
|
|
//! use std::cell::Cell;
|
|
|
|
@ -185,6 +184,11 @@
|
|
|
|
|
//! }
|
|
|
|
|
//! ```
|
|
|
|
|
//!
|
|
|
|
|
//! [`Arc<T>`]: ../../std/sync/struct.Arc.html
|
|
|
|
|
//! [`Rc<T>`]: ../../std/rc/struct.Rc.html
|
|
|
|
|
//! [`RwLock<T>`]: ../../std/sync/struct.RwLock.html
|
|
|
|
|
//! [`Mutex<T>`]: ../../std/sync/struct.Mutex.html
|
|
|
|
|
//! [`atomic`]: ../../core/sync/atomic/index.html
|
|
|
|
|
|
|
|
|
|
#![stable(feature = "rust1", since = "1.0.0")]
|
|
|
|
|
|
|
|
|
|