From dec23d41a607b78c590ab9672815ff53c1e282a7 Mon Sep 17 00:00:00 2001 From: Nicolas Silva Date: Sun, 21 May 2017 16:00:04 +0200 Subject: [PATCH] Update Rc and Arc documentation. It was decided in the RFC discussion https://github.com/rust-lang/rfcs/pull/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. --- src/liballoc/arc.rs | 44 +++++++++++++++++++++++++++++------------ src/liballoc/rc.rs | 48 +++++++++++++++++++++++++++++++-------------- 2 files changed, 64 insertions(+), 28 deletions(-) diff --git a/src/liballoc/arc.rs b/src/liballoc/arc.rs index 27ecefe043b1e..5faf4dcccaf91 100644 --- a/src/liballoc/arc.rs +++ b/src/liballoc/arc.rs @@ -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`][`arc`] and [`Weak`][`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` automatically dereferences to `T` (via the [`Deref`][deref] trait), @@ -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); @@ -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); @@ -282,7 +300,7 @@ impl Arc { /// 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] @@ -451,7 +469,7 @@ impl Arc { /// 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. @@ -499,7 +517,7 @@ impl Arc { /// 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)); @@ -524,7 +542,7 @@ impl Clone for Arc { /// /// let five = Arc::new(5); /// - /// five.clone(); + /// Arc::clone(&five); /// ``` #[inline] fn clone(&self) -> Arc { @@ -591,7 +609,7 @@ impl Arc { /// 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 @@ -679,7 +697,7 @@ impl Arc { /// *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] @@ -751,7 +769,7 @@ unsafe impl<#[may_dangle] T: ?Sized> Drop for Arc { /// } /// /// let foo = Arc::new(Foo); - /// let foo2 = foo.clone(); + /// let foo2 = Arc::clone(&foo); /// /// drop(foo); // Doesn't print anything /// drop(foo2); // Prints "dropped!" @@ -903,11 +921,11 @@ impl Clone for Weak { /// # 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 { @@ -956,7 +974,7 @@ impl Drop for Weak { /// # Examples /// /// ``` - /// use std::sync::Arc; + /// use std::sync::{Arc, Weak}; /// /// struct Foo; /// @@ -968,7 +986,7 @@ impl Drop for Weak { /// /// 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!" diff --git a/src/liballoc/rc.rs b/src/liballoc/rc.rs index d6dbf77bfac77..33951b911dd51 100644 --- a/src/liballoc/rc.rs +++ b/src/liballoc/rc.rs @@ -55,6 +55,24 @@ //! [`Weak`][`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`][`Rc`] and [`Weak`][`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`. @@ -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`. @@ -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), //! } //! ); //! @@ -316,7 +334,7 @@ impl Rc { /// 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] @@ -508,7 +526,7 @@ impl Rc { /// 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)); /// ``` @@ -550,7 +568,7 @@ impl Rc { /// *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] @@ -576,7 +594,7 @@ impl Rc { /// 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)); @@ -608,7 +626,7 @@ impl Rc { /// 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 @@ -680,7 +698,7 @@ unsafe impl<#[may_dangle] T: ?Sized> Drop for Rc { /// } /// /// let foo = Rc::new(Foo); - /// let foo2 = foo.clone(); + /// let foo2 = Rc::clone(&foo); /// /// drop(foo); // Doesn't print anything /// drop(foo2); // Prints "dropped!" @@ -720,7 +738,7 @@ impl Clone for Rc { /// /// let five = Rc::new(5); /// - /// five.clone(); + /// Rc::clone(&five); /// ``` #[inline] fn clone(&self) -> Rc { @@ -1050,7 +1068,7 @@ impl Drop for Weak { /// # Examples /// /// ``` - /// use std::rc::Rc; + /// use std::rc::{Rc, Weak}; /// /// struct Foo; /// @@ -1062,7 +1080,7 @@ impl Drop for Weak { /// /// 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!" @@ -1090,11 +1108,11 @@ impl Clone for Weak { /// # 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 {