Skip to content

Commit 214d8e3

Browse files
Rollup merge of #88156 - steffahn:arc_make_mut_and_weak, r=Mark-Simulacrum
Adjust / fix documentation of `Arc::make_mut` Related discussion in the users forum: [Whatʼs this alleged difference between Arc::make_mut and Rc::make_mut? – The Rust Programming Language Forum](https://users.rust-lang.org/t/what-s-this-alleged-difference-between-arc-make-mut-and-rc-make-mut/63747?u=steffahn) Also includes a small formatting improvement in the documentation of `Rc::make_mut`. This PR makes the two documentations in question complete analogs. The previously claimed point in which one “differs from the behavior of” the other turns out to be incorrect, AFAIK. One remaining inaccuracy: `Weak` pointers aren’t disassociated from the allocation but only from the contained value, i.e. in case of outstanding `Weak` pointers there still is a new allocation created, just the call to `.clone()` is avoided, instead the value is moved from one allocation to the other. `@rustbot` label T-libs-api, A-docs
2 parents ccefe27 + 90354c7 commit 214d8e3

File tree

2 files changed

+39
-19
lines changed

2 files changed

+39
-19
lines changed

library/alloc/src/rc.rs

+11-9
Original file line numberDiff line numberDiff line change
@@ -1011,7 +1011,7 @@ impl<T: ?Sized> Rc<T> {
10111011
/// mutate a shared value.
10121012
///
10131013
/// See also [`make_mut`][make_mut], which will [`clone`][clone]
1014-
/// the inner value when there are other pointers.
1014+
/// the inner value when there are other `Rc` pointers.
10151015
///
10161016
/// [make_mut]: Rc::make_mut
10171017
/// [clone]: Clone::clone
@@ -1100,10 +1100,12 @@ impl<T: Clone> Rc<T> {
11001100
/// [`clone`] the inner value to a new allocation to ensure unique ownership. This is also
11011101
/// referred to as clone-on-write.
11021102
///
1103-
/// If there are no other `Rc` pointers to this allocation, then [`Weak`]
1104-
/// pointers to this allocation will be disassociated.
1103+
/// However, if there are no other `Rc` pointers to this allocation, but some [`Weak`]
1104+
/// pointers, then the [`Weak`] pointers will be disassociated and the inner value will not
1105+
/// be cloned.
11051106
///
1106-
/// See also [`get_mut`], which will fail rather than cloning.
1107+
/// See also [`get_mut`], which will fail rather than cloning the inner value
1108+
/// or diassociating [`Weak`] pointers.
11071109
///
11081110
/// [`clone`]: Clone::clone
11091111
/// [`get_mut`]: Rc::get_mut
@@ -1115,11 +1117,11 @@ impl<T: Clone> Rc<T> {
11151117
///
11161118
/// let mut data = Rc::new(5);
11171119
///
1118-
/// *Rc::make_mut(&mut data) += 1; // Won't clone anything
1119-
/// let mut other_data = Rc::clone(&data); // Won't clone inner data
1120-
/// *Rc::make_mut(&mut data) += 1; // Clones inner data
1121-
/// *Rc::make_mut(&mut data) += 1; // Won't clone anything
1122-
/// *Rc::make_mut(&mut other_data) *= 2; // Won't clone anything
1120+
/// *Rc::make_mut(&mut data) += 1; // Won't clone anything
1121+
/// let mut other_data = Rc::clone(&data); // Won't clone inner data
1122+
/// *Rc::make_mut(&mut data) += 1; // Clones inner data
1123+
/// *Rc::make_mut(&mut data) += 1; // Won't clone anything
1124+
/// *Rc::make_mut(&mut other_data) *= 2; // Won't clone anything
11231125
///
11241126
/// // Now `data` and `other_data` point to different allocations.
11251127
/// assert_eq!(*data, 8);

library/alloc/src/sync.rs

+28-10
Original file line numberDiff line numberDiff line change
@@ -1346,18 +1346,19 @@ impl<T: ?Sized> Receiver for Arc<T> {}
13461346
impl<T: Clone> Arc<T> {
13471347
/// Makes a mutable reference into the given `Arc`.
13481348
///
1349-
/// If there are other `Arc` or [`Weak`] pointers to the same allocation,
1350-
/// then `make_mut` will create a new allocation and invoke [`clone`][clone] on the inner value
1351-
/// to ensure unique ownership. This is also referred to as clone-on-write.
1349+
/// If there are other `Arc` pointers to the same allocation, then `make_mut` will
1350+
/// [`clone`] the inner value to a new allocation to ensure unique ownership. This is also
1351+
/// referred to as clone-on-write.
13521352
///
1353-
/// Note that this differs from the behavior of [`Rc::make_mut`] which disassociates
1354-
/// any remaining `Weak` pointers.
1353+
/// However, if there are no other `Arc` pointers to this allocation, but some [`Weak`]
1354+
/// pointers, then the [`Weak`] pointers will be disassociated and the inner value will not
1355+
/// be cloned.
13551356
///
1356-
/// See also [`get_mut`][get_mut], which will fail rather than cloning.
1357+
/// See also [`get_mut`], which will fail rather than cloning the inner value
1358+
/// or diassociating [`Weak`] pointers.
13571359
///
1358-
/// [clone]: Clone::clone
1359-
/// [get_mut]: Arc::get_mut
1360-
/// [`Rc::make_mut`]: super::rc::Rc::make_mut
1360+
/// [`clone`]: Clone::clone
1361+
/// [`get_mut`]: Arc::get_mut
13611362
///
13621363
/// # Examples
13631364
///
@@ -1376,6 +1377,23 @@ impl<T: Clone> Arc<T> {
13761377
/// assert_eq!(*data, 8);
13771378
/// assert_eq!(*other_data, 12);
13781379
/// ```
1380+
///
1381+
/// [`Weak`] pointers will be disassociated:
1382+
///
1383+
/// ```
1384+
/// use std::sync::Arc;
1385+
///
1386+
/// let mut data = Arc::new(75);
1387+
/// let weak = Arc::downgrade(&data);
1388+
///
1389+
/// assert!(75 == *data);
1390+
/// assert!(75 == *weak.upgrade().unwrap());
1391+
///
1392+
/// *Arc::make_mut(&mut data) += 1;
1393+
///
1394+
/// assert!(76 == *data);
1395+
/// assert!(weak.upgrade().is_none());
1396+
/// ```
13791397
#[cfg(not(no_global_oom_handling))]
13801398
#[inline]
13811399
#[stable(feature = "arc_unique", since = "1.4.0")]
@@ -1441,7 +1459,7 @@ impl<T: ?Sized> Arc<T> {
14411459
/// mutate a shared value.
14421460
///
14431461
/// See also [`make_mut`][make_mut], which will [`clone`][clone]
1444-
/// the inner value when there are other pointers.
1462+
/// the inner value when there are other `Arc` pointers.
14451463
///
14461464
/// [make_mut]: Arc::make_mut
14471465
/// [clone]: Clone::clone

0 commit comments

Comments
 (0)