Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update to Rc and Arc documentation to favor the Rc::clone(&ptr) syntax. #42137

Merged
merged 1 commit into from
May 27, 2017
Merged

Update to Rc and Arc documentation to favor the Rc::clone(&ptr) syntax. #42137

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 31 additions & 13 deletions src/liballoc/arc.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -91,6 +91,24 @@ const MAX_REFCOUNT: usize = (isize::MAX) as usize;
/// strong `Arc` pointers from parent nodes to children, and [`Weak`][weak]
/// pointers from children back to their parents.
///
/// # Cloning references
///
/// Creating a new reference from an existing reference counted pointer is done using the
/// `Clone` trait implemented for [`Arc<T>`][`arc`] and [`Weak<T>`][`weak`].
///
/// ```
/// use std::sync::Arc;
/// let foo = Arc::new(vec![1.0, 2.0, 3.0]);
/// // The two syntaxes below are equivalent.
/// let a = foo.clone();
/// let b = Arc::clone(&foo);
/// // a and b both point to the same memory location as foo.
/// ```
///
/// The `Arc::clone(&from)` syntax is the most idiomatic because it conveys more explicitly
/// the meaning of the code. In the example above, this syntax makes it easier to see that
/// this code is creating a new reference rather than copying the whole content of foo.
///
/// ## `Deref` behavior
///
/// `Arc<T>` automatically dereferences to `T` (via the [`Deref`][deref] trait),
Expand Down Expand Up @@ -138,7 +156,7 @@ const MAX_REFCOUNT: usize = (isize::MAX) as usize;
/// let five = Arc::new(5);
///
/// for _ in 0..10 {
/// let five = five.clone();
/// let five = Arc::clone(&five);
///
/// thread::spawn(move || {
/// println!("{:?}", five);
Expand All @@ -158,7 +176,7 @@ const MAX_REFCOUNT: usize = (isize::MAX) as usize;
/// let val = Arc::new(AtomicUsize::new(5));
///
/// for _ in 0..10 {
/// let val = val.clone();
/// let val = Arc::clone(&val);
///
/// thread::spawn(move || {
/// let v = val.fetch_add(1, Ordering::SeqCst);
Expand Down Expand Up @@ -282,7 +300,7 @@ impl<T> Arc<T> {
/// assert_eq!(Arc::try_unwrap(x), Ok(3));
///
/// let x = Arc::new(4);
/// let _y = x.clone();
/// let _y = Arc::clone(&x);
/// assert_eq!(*Arc::try_unwrap(x).unwrap_err(), 4);
/// ```
#[inline]
Expand Down Expand Up @@ -451,7 +469,7 @@ impl<T: ?Sized> Arc<T> {
/// use std::sync::Arc;
///
/// let five = Arc::new(5);
/// let _also_five = five.clone();
/// let _also_five = Arc::clone(&five);
///
/// // This assertion is deterministic because we haven't shared
/// // the `Arc` between threads.
Expand Down Expand Up @@ -499,7 +517,7 @@ impl<T: ?Sized> Arc<T> {
/// use std::sync::Arc;
///
/// let five = Arc::new(5);
/// let same_five = five.clone();
/// let same_five = Arc::clone(&five);
/// let other_five = Arc::new(5);
///
/// assert!(Arc::ptr_eq(&five, &same_five));
Expand All @@ -524,7 +542,7 @@ impl<T: ?Sized> Clone for Arc<T> {
///
/// let five = Arc::new(5);
///
/// five.clone();
/// Arc::clone(&five);
/// ```
#[inline]
fn clone(&self) -> Arc<T> {
Expand Down Expand Up @@ -591,7 +609,7 @@ impl<T: Clone> Arc<T> {
/// let mut data = Arc::new(5);
///
/// *Arc::make_mut(&mut data) += 1; // Won't clone anything
/// let mut other_data = data.clone(); // Won't clone inner data
/// let mut other_data = Arc::clone(&data); // Won't clone inner data
/// *Arc::make_mut(&mut data) += 1; // Clones inner data
/// *Arc::make_mut(&mut data) += 1; // Won't clone anything
/// *Arc::make_mut(&mut other_data) *= 2; // Won't clone anything
Expand Down Expand Up @@ -679,7 +697,7 @@ impl<T: ?Sized> Arc<T> {
/// *Arc::get_mut(&mut x).unwrap() = 4;
/// assert_eq!(*x, 4);
///
/// let _y = x.clone();
/// let _y = Arc::clone(&x);
/// assert!(Arc::get_mut(&mut x).is_none());
/// ```
#[inline]
Expand Down Expand Up @@ -751,7 +769,7 @@ unsafe impl<#[may_dangle] T: ?Sized> Drop for Arc<T> {
/// }
///
/// let foo = Arc::new(Foo);
/// let foo2 = foo.clone();
/// let foo2 = Arc::clone(&foo);
///
/// drop(foo); // Doesn't print anything
/// drop(foo2); // Prints "dropped!"
Expand Down Expand Up @@ -903,11 +921,11 @@ impl<T: ?Sized> Clone for Weak<T> {
/// # Examples
///
/// ```
/// use std::sync::Arc;
/// use std::sync::{Arc, Weak};
///
/// let weak_five = Arc::downgrade(&Arc::new(5));
///
/// weak_five.clone();
/// Weak::clone(&weak_five);
/// ```
#[inline]
fn clone(&self) -> Weak<T> {
Expand Down Expand Up @@ -956,7 +974,7 @@ impl<T: ?Sized> Drop for Weak<T> {
/// # Examples
///
/// ```
/// use std::sync::Arc;
/// use std::sync::{Arc, Weak};
///
/// struct Foo;
///
Expand All @@ -968,7 +986,7 @@ impl<T: ?Sized> Drop for Weak<T> {
///
/// let foo = Arc::new(Foo);
/// let weak_foo = Arc::downgrade(&foo);
/// let other_weak_foo = weak_foo.clone();
/// let other_weak_foo = Weak::clone(&weak_foo);
///
/// drop(weak_foo); // Doesn't print anything
/// drop(foo); // Prints "dropped!"
Expand Down
48 changes: 33 additions & 15 deletions src/liballoc/rc.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,24 @@
//! [`Weak<T>`][`Weak`] does not auto-dereference to `T`, because the value may have
//! already been destroyed.
//!
//! # Cloning references
//!
//! Creating a new reference from an existing reference counted pointer is done using the
//! `Clone` trait implemented for [`Rc<T>`][`Rc`] and [`Weak<T>`][`Weak`].
//!
//! ```
//! use std::rc::Rc;
//! let foo = Rc::new(vec![1.0, 2.0, 3.0]);
//! // The two syntaxes below are equivalent.
//! let a = foo.clone();
//! let b = Rc::clone(&foo);
//! // a and b both point to the same memory location as foo.
//! ```
//!
//! The `Rc::clone(&from)` syntax is the most idiomatic because it conveys more explicitly
//! the meaning of the code. In the example above, this syntax makes it easier to see that
//! this code is creating a new reference rather than copying the whole content of foo.
//!
//! # Examples
//!
//! Consider a scenario where a set of `Gadget`s are owned by a given `Owner`.
Expand Down Expand Up @@ -90,11 +108,11 @@
//! // the reference count in the process.
//! let gadget1 = Gadget {
//! id: 1,
//! owner: gadget_owner.clone(),
//! owner: Rc::clone(&gadget_owner),
//! };
//! let gadget2 = Gadget {
//! id: 2,
//! owner: gadget_owner.clone(),
//! owner: Rc::clone(&gadget_owner),
//! };
//!
//! // Dispose of our local variable `gadget_owner`.
Expand Down Expand Up @@ -163,13 +181,13 @@
//! let gadget1 = Rc::new(
//! Gadget {
//! id: 1,
//! owner: gadget_owner.clone(),
//! owner: Rc::clone(&gadget_owner),
//! }
//! );
//! let gadget2 = Rc::new(
//! Gadget {
//! id: 2,
//! owner: gadget_owner.clone(),
//! owner: Rc::clone(&gadget_owner),
//! }
//! );
//!
Expand Down Expand Up @@ -316,7 +334,7 @@ impl<T> Rc<T> {
/// assert_eq!(Rc::try_unwrap(x), Ok(3));
///
/// let x = Rc::new(4);
/// let _y = x.clone();
/// let _y = Rc::clone(&x);
/// assert_eq!(*Rc::try_unwrap(x).unwrap_err(), 4);
/// ```
#[inline]
Expand Down Expand Up @@ -508,7 +526,7 @@ impl<T: ?Sized> Rc<T> {
/// use std::rc::Rc;
///
/// let five = Rc::new(5);
/// let _also_five = five.clone();
/// let _also_five = Rc::clone(&five);
///
/// assert_eq!(2, Rc::strong_count(&five));
/// ```
Expand Down Expand Up @@ -550,7 +568,7 @@ impl<T: ?Sized> Rc<T> {
/// *Rc::get_mut(&mut x).unwrap() = 4;
/// assert_eq!(*x, 4);
///
/// let _y = x.clone();
/// let _y = Rc::clone(&x);
/// assert!(Rc::get_mut(&mut x).is_none());
/// ```
#[inline]
Expand All @@ -576,7 +594,7 @@ impl<T: ?Sized> Rc<T> {
/// use std::rc::Rc;
///
/// let five = Rc::new(5);
/// let same_five = five.clone();
/// let same_five = Rc::clone(&five);
/// let other_five = Rc::new(5);
///
/// assert!(Rc::ptr_eq(&five, &same_five));
Expand Down Expand Up @@ -608,7 +626,7 @@ 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 = data.clone(); // Won't clone inner data
/// 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
Expand Down Expand Up @@ -680,7 +698,7 @@ unsafe impl<#[may_dangle] T: ?Sized> Drop for Rc<T> {
/// }
///
/// let foo = Rc::new(Foo);
/// let foo2 = foo.clone();
/// let foo2 = Rc::clone(&foo);
///
/// drop(foo); // Doesn't print anything
/// drop(foo2); // Prints "dropped!"
Expand Down Expand Up @@ -720,7 +738,7 @@ impl<T: ?Sized> Clone for Rc<T> {
///
/// let five = Rc::new(5);
///
/// five.clone();
/// Rc::clone(&five);
/// ```
#[inline]
fn clone(&self) -> Rc<T> {
Expand Down Expand Up @@ -1050,7 +1068,7 @@ impl<T: ?Sized> Drop for Weak<T> {
/// # Examples
///
/// ```
/// use std::rc::Rc;
/// use std::rc::{Rc, Weak};
///
/// struct Foo;
///
Expand All @@ -1062,7 +1080,7 @@ impl<T: ?Sized> Drop for Weak<T> {
///
/// let foo = Rc::new(Foo);
/// let weak_foo = Rc::downgrade(&foo);
/// let other_weak_foo = weak_foo.clone();
/// let other_weak_foo = Weak::clone(&weak_foo);
///
/// drop(weak_foo); // Doesn't print anything
/// drop(foo); // Prints "dropped!"
Expand Down Expand Up @@ -1090,11 +1108,11 @@ impl<T: ?Sized> Clone for Weak<T> {
/// # Examples
///
/// ```
/// use std::rc::Rc;
/// use std::rc::{Rc, Weak};
///
/// let weak_five = Rc::downgrade(&Rc::new(5));
///
/// weak_five.clone();
/// Weak::clone(&weak_five);
/// ```
#[inline]
fn clone(&self) -> Weak<T> {
Expand Down