diff --git a/src/SUMMARY.md b/src/SUMMARY.md index b181c87b..5c0066ad 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -140,7 +140,7 @@ - [Exercise: Builder Type](memory-management/exercise.md) - [Solution](memory-management/solution.md) - [Smart Pointers](smart-pointers.md) - - [`Box`](smart-pointers/box.md) + - [`Box`](smart-pointers/box.md) - [`Rc`](smart-pointers/rc.md) - [Owned Trait Objects](smart-pointers/trait-objects.md) - [Exercise: Binary Tree](smart-pointers/exercise.md) diff --git a/src/borrowing/interior-mutability.md b/src/borrowing/interior-mutability.md index def874e9..4fc543e7 100644 --- a/src/borrowing/interior-mutability.md +++ b/src/borrowing/interior-mutability.md @@ -14,6 +14,8 @@ while still ensuring safety, typically by performing a runtime check. ## `RefCell` +A [`RefCell`] gives you mutable access to a value behind a shared reference: + ```rust,editable use std::cell::RefCell; @@ -36,9 +38,9 @@ fn main() { ## `Cell` -`Cell` wraps a value and allows getting or setting the value, even with a shared -reference to the `Cell`. However, it does not allow any references to the value. -Since there are no references, borrowing rules cannot be broken. +[`Cell`] wraps a `T` value. It allows getting or setting the value, even with +a shared reference to the `Cell`. However, it does not allow any references to +the value. Since there are no references, the borrowing rules cannot be broken. ```rust,editable use std::cell::Cell; @@ -72,3 +74,6 @@ that safety, and `RefCell` and `Cell` are two of them. have its own cost. + +[`Cell`]: https://doc.rust-lang.org/std/cell/struct.Cell.html +[`RefCell`]: https://doc.rust-lang.org/std/cell/struct.RefCell.html diff --git a/src/concurrency/shared-state/arc.md b/src/concurrency/shared-state/arc.md index 694a6dc2..424f846f 100644 --- a/src/concurrency/shared-state/arc.md +++ b/src/concurrency/shared-state/arc.md @@ -4,7 +4,8 @@ minutes: 5 # `Arc` -[`Arc`][1] allows shared read-only access via `Arc::clone`: +[`Arc`] is a reference-counted shared pointer to `T`. Use this when you need +to refer to the same data from multiple threads: ```rust,editable use std::sync::Arc; @@ -26,18 +27,21 @@ fn main() { } ``` -[1]: https://doc.rust-lang.org/std/sync/struct.Arc.html -
-- `Arc` stands for "Atomic Reference Counted", a thread safe version of `Rc` - that uses atomic operations. +- `Arc` is short for "Atomically Reference Counted". It uses atomic + (thread-safe) CPU instructions to maintain the reference count. `Arc` is a + thread safe version of [`Rc`]. - `Arc` implements `Clone` whether or not `T` does. It implements `Send` and `Sync` if and only if `T` implements them both. - `Arc::clone()` has the cost of atomic operations that get executed, but after that the use of the `T` is free. - Beware of reference cycles, `Arc` does not use a garbage collector to detect them. - - `std::sync::Weak` can help. + - [`std::sync::Weak`] can help avoid reference cycles.
+ +[`Arc`]: https://doc.rust-lang.org/std/sync/struct.Arc.html +[`Rc`]: ../../smart-pointers/rc.md +[`std::sync::Weak`]: https://doc.rust-lang.org/std/sync/struct.Weak.html diff --git a/src/concurrency/shared-state/mutex.md b/src/concurrency/shared-state/mutex.md index 555ee55f..57721a18 100644 --- a/src/concurrency/shared-state/mutex.md +++ b/src/concurrency/shared-state/mutex.md @@ -6,7 +6,7 @@ minutes: 14 [`Mutex`][1] ensures mutual exclusion _and_ allows mutable access to `T` behind a read-only interface (another form of -[interior mutability](../../borrowing/interior-mutability)): +[interior mutability](../../borrowing/interior-mutability.md)): ```rust,editable use std::sync::Mutex; diff --git a/src/smart-pointers/box.md b/src/smart-pointers/box.md index dbf91cd0..bd6b2476 100644 --- a/src/smart-pointers/box.md +++ b/src/smart-pointers/box.md @@ -2,10 +2,10 @@ minutes: 8 --- -# `Box` +# `Box` -[`Box`](https://doc.rust-lang.org/std/boxed/struct.Box.html) is an owned pointer -to data on the heap: +[`Box`](https://doc.rust-lang.org/std/boxed/struct.Box.html) is an owned +pointer to a `T` on the heap: ```rust,editable fn main() { @@ -28,8 +28,7 @@ fn main() { ``` `Box` implements `Deref`, which means that you can -[call methods -from `T` directly on a `Box`](https://doc.rust-lang.org/std/ops/trait.Deref.html#more-on-deref-coercion). +[call methods from `T` directly](https://doc.rust-lang.org/std/ops/trait.Deref.html#more-on-deref-coercion). Recursive data types or data types with dynamic sizes need to use a `Box`: diff --git a/src/smart-pointers/rc.md b/src/smart-pointers/rc.md index 525b3e66..804f6fb5 100644 --- a/src/smart-pointers/rc.md +++ b/src/smart-pointers/rc.md @@ -4,8 +4,8 @@ minutes: 5 # `Rc` -[`Rc`][1] is a reference-counted shared pointer. Use this when you need to refer -to the same data from multiple places: +[`Rc`][1] is a reference-counted shared pointer to `T`. Use this when you +need to refer to the same data from multiple places: ```rust,editable use std::rc::Rc; @@ -25,7 +25,7 @@ fn main() { [1]: https://doc.rust-lang.org/std/rc/struct.Rc.html [2]: ../concurrency/shared-state/arc.md -[3]: https://doc.rust-lang.org/std/sync/struct.Mutex.html +[3]: ../concurrency/shared-state/mutex.md [4]: https://doc.rust-lang.org/std/rc/struct.Weak.html