|
11 | 11 | //! mutate it.
|
12 | 12 | //!
|
13 | 13 | //! Shareable mutable containers exist to permit mutability in a controlled manner, even in the
|
14 |
| -//! presence of aliasing. Both `Cell<T>` and `RefCell<T>` allow doing this in a single-threaded |
| 14 | +//! presence of aliasing. Both [`Cell<T>`] and [`RefCell<T>`] allow doing this in a single-threaded |
15 | 15 | //! way. However, neither `Cell<T>` nor `RefCell<T>` are thread safe (they do not implement
|
16 |
| -//! `Sync`). If you need to do aliasing and mutation between multiple threads it is possible to |
17 |
| -//! use [`Mutex`](../../std/sync/struct.Mutex.html), |
18 |
| -//! [`RwLock`](../../std/sync/struct.RwLock.html) or |
19 |
| -//! [`atomic`](../../core/sync/atomic/index.html) types. |
| 16 | +//! [`Sync`]). If you need to do aliasing and mutation between multiple threads it is possible to |
| 17 | +//! use [`Mutex<T>`], [`RwLock<T>`] or [`atomic`] types. |
20 | 18 | //!
|
21 | 19 | //! Values of the `Cell<T>` and `RefCell<T>` types may be mutated through shared references (i.e.
|
22 | 20 | //! the common `&T` type), whereas most Rust types can only be mutated through unique (`&mut T`)
|
|
28 | 26 | //! one must use the `RefCell<T>` type, acquiring a write lock before mutating. `Cell<T>` provides
|
29 | 27 | //! methods to retrieve and change the current interior value:
|
30 | 28 | //!
|
31 |
| -//! - For types that implement `Copy`, the `get` method retrieves the current interior value. |
32 |
| -//! - For types that implement `Default`, the `take` method replaces the current interior value |
33 |
| -//! with `Default::default()` and returns the replaced value. |
34 |
| -//! - For all types, the `replace` method replaces the current interior value and returns the |
35 |
| -//! replaced value and the `into_inner` method consumes the `Cell<T>` and returns the interior |
36 |
| -//! value. Additionally, the `set` method replaces the interior value, dropping the replaced |
37 |
| -//! value. |
| 29 | +//! - For types that implement [`Copy`], the [`get`](Cell::get) method retrieves the current |
| 30 | +//! interior value. |
| 31 | +//! - For types that implement [`Default`], the [`take`](Cell::take) method replaces the current |
| 32 | +//! interior value with [`Default::default()`] and returns the replaced value. |
| 33 | +//! - For all types, the [`replace`](Cell::replace) method replaces the current interior value and |
| 34 | +//! returns the replaced value and the [`into_inner`](Cell::into_inner) method consumes the |
| 35 | +//! `Cell<T>` and returns the interior value. Additionally, the [`set`](Cell::set) method |
| 36 | +//! replaces the interior value, dropping the replaced value. |
38 | 37 | //!
|
39 | 38 | //! `RefCell<T>` uses Rust's lifetimes to implement 'dynamic borrowing', a process whereby one can
|
40 | 39 | //! claim temporary, exclusive, mutable access to the inner value. Borrows for `RefCell<T>`s are
|
|
54 | 53 | //!
|
55 | 54 | //! * Introducing mutability 'inside' of something immutable
|
56 | 55 | //! * Implementation details of logically-immutable methods.
|
57 |
| -//! * Mutating implementations of `Clone`. |
| 56 | +//! * Mutating implementations of [`Clone`]. |
58 | 57 | //!
|
59 | 58 | //! ## Introducing mutability 'inside' of something immutable
|
60 | 59 | //!
|
61 |
| -//! Many shared smart pointer types, including `Rc<T>` and `Arc<T>`, provide containers that can be |
62 |
| -//! cloned and shared between multiple parties. Because the contained values may be |
| 60 | +//! Many shared smart pointer types, including [`Rc<T>`] and [`Arc<T>`], provide containers that can |
| 61 | +//! be cloned and shared between multiple parties. Because the contained values may be |
63 | 62 | //! multiply-aliased, they can only be borrowed with `&`, not `&mut`. Without cells it would be
|
64 | 63 | //! impossible to mutate data inside of these smart pointers at all.
|
65 | 64 | //!
|
|
91 | 90 | //! ```
|
92 | 91 | //!
|
93 | 92 | //! Note that this example uses `Rc<T>` and not `Arc<T>`. `RefCell<T>`s are for single-threaded
|
94 |
| -//! scenarios. Consider using `RwLock<T>` or `Mutex<T>` if you need shared mutability in a |
| 93 | +//! scenarios. Consider using [`RwLock<T>`] or [`Mutex<T>`] if you need shared mutability in a |
95 | 94 | //! multi-threaded situation.
|
96 | 95 | //!
|
97 | 96 | //! ## Implementation details of logically-immutable methods
|
|
127 | 126 | //! ## Mutating implementations of `Clone`
|
128 | 127 | //!
|
129 | 128 | //! This is simply a special - but common - case of the previous: hiding mutability for operations
|
130 |
| -//! that appear to be immutable. The `clone` method is expected to not change the source value, and |
131 |
| -//! is declared to take `&self`, not `&mut self`. Therefore, any mutation that happens in the |
132 |
| -//! `clone` method must use cell types. For example, `Rc<T>` maintains its reference counts within a |
133 |
| -//! `Cell<T>`. |
| 129 | +//! that appear to be immutable. The [`clone`](Clone::clone) method is expected to not change the |
| 130 | +//! source value, and is declared to take `&self`, not `&mut self`. Therefore, any mutation that |
| 131 | +//! happens in the `clone` method must use cell types. For example, [`Rc<T>`] maintains its |
| 132 | +//! reference counts within a `Cell<T>`. |
134 | 133 | //!
|
135 | 134 | //! ```
|
136 | 135 | //! use std::cell::Cell;
|
|
185 | 184 | //! }
|
186 | 185 | //! ```
|
187 | 186 | //!
|
| 187 | +//! [`Arc<T>`]: ../../std/sync/struct.Arc.html |
| 188 | +//! [`Rc<T>`]: ../../std/rc/struct.Rc.html |
| 189 | +//! [`RwLock<T>`]: ../../std/sync/struct.RwLock.html |
| 190 | +//! [`Mutex<T>`]: ../../std/sync/struct.Mutex.html |
| 191 | +//! [`atomic`]: ../../core/sync/atomic/index.html |
188 | 192 |
|
189 | 193 | #![stable(feature = "rust1", since = "1.0.0")]
|
190 | 194 |
|
|
0 commit comments