nordic-dev.net/rust
nordic-dev.net/rust
2
0
Fork 0
mirror of https://github.com/rust-lang/rust.git synced 2024-11-01 23:12:02 +00:00
Code Issues Packages Projects Releases Wiki Activity

Rollup merge of #88156 - steffahn:arc_make_mut_and_weak, r=Mark-Simulacrum

Browse Source 
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
This commit is contained in:
Léo Lanteri Thauvin 2021-08-25 15:48:48 +02:00 committed by GitHub
commit 214d8e3cd4
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 39 additions and 19 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
library/alloc/src/rc.rs
View File

@ -1011,7 +1011,7 @@ impl<T: ?Sized> Rc<T> {
/// mutate a shared value.
///
/// See also [`make_mut`][make_mut], which will [`clone`][clone]
/// the inner value when there are other pointers.
/// the inner value when there are other `Rc` pointers.
///
/// [make_mut]: Rc::make_mut
/// [clone]: Clone::clone
@ -1100,10 +1100,12 @@ impl<T: Clone> Rc<T> {
/// [`clone`] the inner value to a new allocation to ensure unique ownership. This is also
/// referred to as clone-on-write.
///
/// If there are no other `Rc` pointers to this allocation, then [`Weak`]
/// pointers to this allocation will be disassociated.
/// However, if there are no other `Rc` pointers to this allocation, but some [`Weak`]
/// pointers, then the [`Weak`] pointers will be disassociated and the inner value will not
/// be cloned.
///
/// See also [`get_mut`], which will fail rather than cloning.
/// See also [`get_mut`], which will fail rather than cloning the inner value
/// or diassociating [`Weak`] pointers.
///
/// [`clone`]: Clone::clone
/// [`get_mut`]: Rc::get_mut
@ -1115,11 +1117,11 @@ impl<T: Clone> Rc<T> {
///
/// let mut data = Rc::new(5);
///
/// *Rc::make_mut(&mut data) += 1; // Won't clone anything
/// let mut other_data = Rc::clone(&data); // Won't clone inner data
/// *Rc::make_mut(&mut data) += 1; // Clones inner data
/// *Rc::make_mut(&mut data) += 1; // Won't clone anything
/// *Rc::make_mut(&mut other_data) *= 2; // Won't clone anything
/// *Rc::make_mut(&mut data) += 1; // Won't clone anything
/// let mut other_data = Rc::clone(&data); // Won't clone inner data
/// *Rc::make_mut(&mut data) += 1; // Clones inner data
/// *Rc::make_mut(&mut data) += 1; // Won't clone anything
/// *Rc::make_mut(&mut other_data) *= 2; // Won't clone anything
///
/// // Now `data` and `other_data` point to different allocations.
/// assert_eq!(*data, 8);

38
library/alloc/src/sync.rs
View File

@ -1346,18 +1346,19 @@ impl<T: ?Sized> Receiver for Arc<T> {}
impl<T: Clone> Arc<T> {
/// Makes a mutable reference into the given `Arc`.
///
/// If there are other `Arc` or [`Weak`] pointers to the same allocation,
/// then `make_mut` will create a new allocation and invoke [`clone`][clone] on the inner value
/// to ensure unique ownership. This is also referred to as clone-on-write.
/// If there are other `Arc` pointers to the same allocation, then `make_mut` will
/// [`clone`] the inner value to a new allocation to ensure unique ownership. This is also
/// referred to as clone-on-write.
///
/// Note that this differs from the behavior of [`Rc::make_mut`] which disassociates
/// any remaining `Weak` pointers.
/// However, if there are no other `Arc` pointers to this allocation, but some [`Weak`]
/// pointers, then the [`Weak`] pointers will be disassociated and the inner value will not
/// be cloned.
///
/// See also [`get_mut`][get_mut], which will fail rather than cloning.
/// See also [`get_mut`], which will fail rather than cloning the inner value
/// or diassociating [`Weak`] pointers.
///
/// [clone]: Clone::clone
/// [get_mut]: Arc::get_mut
/// [`Rc::make_mut`]: super::rc::Rc::make_mut
/// [`clone`]: Clone::clone
/// [`get_mut`]: Arc::get_mut
///
/// # Examples
///
@ -1376,6 +1377,23 @@ impl<T: Clone> Arc<T> {
/// assert_eq!(*data, 8);
/// assert_eq!(*other_data, 12);
/// ```
///
/// [`Weak`] pointers will be disassociated:
///
/// ```
/// use std::sync::Arc;
///
/// let mut data = Arc::new(75);
/// let weak = Arc::downgrade(&data);
///
/// assert!(75 == *data);
/// assert!(75 == *weak.upgrade().unwrap());
///
/// *Arc::make_mut(&mut data) += 1;
///
/// assert!(76 == *data);
/// assert!(weak.upgrade().is_none());
/// ```
#[cfg(not(no_global_oom_handling))]
#[inline]
#[stable(feature = "arc_unique", since = "1.4.0")]
@ -1441,7 +1459,7 @@ impl<T: ?Sized> Arc<T> {
/// mutate a shared value.
///
/// See also [`make_mut`][make_mut], which will [`clone`][clone]
/// the inner value when there are other pointers.
/// the inner value when there are other `Arc` pointers.
///
/// [make_mut]: Arc::make_mut
/// [clone]: Clone::clone