Skip to content

Commit

Permalink
Update Rc and Arc documentation.
Browse files Browse the repository at this point in the history 
It was decided in the RFC discussion rust-lang/rfcs#1954 to make the function call syntax Rc::clone(&foo) the idiomatic way to clone a reference counted pointer (over the method call syntax foo.clone(). This change updates the documentation of Rc, Arc and their respoective Weak pointers to reflect it and bring more exposure to the existence of the function call syntax.
  • Loading branch information
@nical
nical committed May 22, 2017
1 parent 84a155f commit dec23d4
Show file tree
Hide file tree
Showing 2 changed files with 64 additions and 28 deletions.
44 changes: 31 additions & 13 deletions src/liballoc/arc.rs
View file
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
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

0 comments on commit dec23d4

Please sign in to comment.