diff --git a/src/liballoc/rc.rs b/src/liballoc/rc.rs index df84ac9aec935..e626d63937bc2 100644 --- a/src/liballoc/rc.rs +++ b/src/liballoc/rc.rs @@ -8,27 +8,25 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. -//! Task-local reference-counted boxes (the `Rc` type). +//! Task-local reference-counted boxes (the `Rc` type). //! -//! The `Rc` type provides shared ownership of an immutable value. Destruction is -//! deterministic, and will occur as soon as the last owner is gone. It is marked -//! as non-sendable because it avoids the overhead of atomic reference counting. +//! The `Rc` type provides shared ownership of an immutable value. Destruction is deterministic, +//! and will occur as soon as the last owner is gone. It is marked as non-sendable because it +//! avoids the overhead of atomic reference counting. //! -//! The `downgrade` method can be used to create a non-owning `Weak` pointer to the -//! box. A `Weak` pointer can be upgraded to an `Rc` pointer, but will return -//! `None` if the value has already been freed. +//! The `downgrade` method can be used to create a non-owning `Weak` pointer to the box. A +//! `Weak` pointer can be upgraded to an `Rc` pointer, but will return `None` if the value +//! has already been dropped. //! -//! For example, a tree with parent pointers can be represented by putting the -//! nodes behind strong `Rc` pointers, and then storing the parent pointers as -//! `Weak` pointers. +//! For example, a tree with parent pointers can be represented by putting the nodes behind strong +//! `Rc` pointers, and then storing the parent pointers as `Weak` pointers. //! //! # Examples //! -//! Consider a scenario where a set of `Gadget`s are owned by a given `Owner`. -//! We want to have our `Gadget`s point to their `Owner`. We can't do this with -//! unique ownership, because more than one gadget may belong to the same -//! `Owner`. `Rc` allows us to share an `Owner` between multiple `Gadget`s, and -//! have the `Owner` kept alive as long as any `Gadget` points at it. +//! Consider a scenario where a set of `Gadget`s are owned by a given `Owner`. We want to have our +//! `Gadget`s point to their `Owner`. We can't do this with unique ownership, because more than one +//! gadget may belong to the same `Owner`. `Rc` allows us to share an `Owner` between multiple +//! `Gadget`s, and have the `Owner` remain allocated as long as any `Gadget` points at it. //! //! ```rust //! use std::rc::Rc; @@ -51,7 +49,7 @@ //! ); //! //! // Create Gadgets belonging to gadget_owner. To increment the reference -//! // count we clone the Rc object. +//! // count we clone the `Rc` object. //! let gadget1 = Gadget { id: 1, owner: gadget_owner.clone() }; //! let gadget2 = Gadget { id: 2, owner: gadget_owner.clone() }; //! @@ -60,8 +58,8 @@ //! // Despite dropping gadget_owner, we're still able to print out the name of //! // the Owner of the Gadgets. This is because we've only dropped the //! // reference count object, not the Owner it wraps. As long as there are -//! // other Rc objects pointing at the same Owner, it will stay alive. Notice -//! // that the Rc wrapper around Gadget.owner gets automatically dereferenced +//! // other `Rc` objects pointing at the same Owner, it will remain allocated. Notice +//! // that the `Rc` wrapper around Gadget.owner gets automatically dereferenced //! // for us. //! println!("Gadget {} owned by {}", gadget1.id, gadget1.owner.name); //! println!("Gadget {} owned by {}", gadget2.id, gadget2.owner.name); @@ -72,23 +70,19 @@ //! } //! ``` //! -//! If our requirements change, and we also need to be able to traverse from -//! Owner → Gadget, we will run into problems: an `Rc` pointer from Owner → Gadget -//! introduces a cycle between the objects. This means that their reference counts -//! can never reach 0, and the objects will stay alive: a memory leak. In order to -//! get around this, we can use `Weak` pointers. These are reference counted -//! pointers that don't keep an object alive if there are no normal `Rc` (or -//! *strong*) pointers left. +//! If our requirements change, and we also need to be able to traverse from Owner → Gadget, we +//! will run into problems: an `Rc` pointer from Owner → Gadget introduces a cycle between the +//! objects. This means that their reference counts can never reach 0, and the objects will remain +//! allocated: a memory leak. In order to get around this, we can use `Weak` pointers. These +//! pointers don't contribute to the total count. //! -//! Rust actually makes it somewhat difficult to produce this loop in the first -//! place: in order to end up with two objects that point at each other, one of -//! them needs to be mutable. This is problematic because `Rc` enforces memory -//! safety by only giving out shared references to the object it wraps, and these -//! don't allow direct mutation. We need to wrap the part of the object we wish to -//! mutate in a `RefCell`, which provides *interior mutability*: a method to -//! achieve mutability through a shared reference. `RefCell` enforces Rust's -//! borrowing rules at runtime. Read the `Cell` documentation for more details on -//! interior mutability. +//! Rust actually makes it somewhat difficult to produce this loop in the first place: in order to +//! end up with two objects that point at each other, one of them needs to be mutable. This is +//! problematic because `Rc` enforces memory safety by only giving out shared references to the +//! object it wraps, and these don't allow direct mutation. We need to wrap the part of the object +//! we wish to mutate in a `RefCell`, which provides *interior mutability*: a method to achieve +//! mutability through a shared reference. `RefCell` enforces Rust's borrowing rules at runtime. +//! Read the `Cell` documentation for more details on interior mutability. //! //! ```rust //! use std::rc::Rc; @@ -131,7 +125,7 @@ //! for gadget_opt in gadget_owner.gadgets.borrow().iter() { //! //! // gadget_opt is a Weak. Since weak pointers can't guarantee -//! // that their object is still alive, we need to call upgrade() on them +//! // that their object is still allocated, we need to call upgrade() on them //! // to turn them into a strong reference. This returns an Option, which //! // contains a reference to our object if it still exists. //! let gadget = gadget_opt.upgrade().unwrap(); @@ -139,7 +133,7 @@ //! } //! //! // At the end of the method, gadget_owner, gadget1 and gadget2 get -//! // destroyed. There are now no strong (Rc) references to the gadgets. +//! // destroyed. There are now no strong (`Rc`) references to the gadgets. //! // Once they get destroyed, the Gadgets get destroyed. This zeroes the //! // reference count on Gadget Man, so he gets destroyed as well. //! } @@ -169,6 +163,8 @@ struct RcBox { } /// An immutable reference-counted pointer type. +/// +/// See the [module level documentation](../index.html) for more. #[unsafe_no_drop_flag] #[stable] pub struct Rc { @@ -180,7 +176,15 @@ pub struct Rc { } impl Rc { - /// Constructs a new reference-counted pointer. + /// Constructs a new `Rc`. + /// + /// # Examples + /// + /// ``` + /// use std::rc::Rc; + /// + /// let five = Rc::new(5i); + /// ``` #[stable] pub fn new(value: T) -> Rc { unsafe { @@ -201,7 +205,17 @@ impl Rc { } } - /// Downgrades the reference-counted pointer to a weak reference. + /// Downgrades the `Rc` to a `Weak` reference. + /// + /// # Examples + /// + /// ``` + /// use std::rc::Rc; + /// + /// let five = Rc::new(5i); + /// + /// let weak_five = five.downgrade(); + /// ``` #[experimental = "Weak pointers may not belong in this module"] pub fn downgrade(&self) -> Weak { self.inc_weak(); @@ -223,27 +237,36 @@ pub fn weak_count(this: &Rc) -> uint { this.weak() - 1 } #[experimental] pub fn strong_count(this: &Rc) -> uint { this.strong() } -/// Returns true if the `Rc` currently has unique ownership. +/// Returns true if there are no other `Rc` or `Weak` values that share the same inner value. +/// +/// # Examples +/// +/// ``` +/// use std::rc; +/// use std::rc::Rc; +/// +/// let five = Rc::new(5i); /// -/// Unique ownership means that there are no other `Rc` or `Weak` values -/// that share the same contents. +/// rc::is_unique(&five); +/// ``` #[inline] #[experimental] pub fn is_unique(rc: &Rc) -> bool { weak_count(rc) == 0 && strong_count(rc) == 1 } -/// Unwraps the contained value if the `Rc` has unique ownership. +/// Unwraps the contained value if the `Rc` is unique. /// -/// If the `Rc` does not have unique ownership, `Err` is returned with the -/// same `Rc`. +/// If the `Rc` is not unique, an `Err` is returned with the same `Rc`. /// /// # Example /// /// ``` /// use std::rc::{mod, Rc}; +/// /// let x = Rc::new(3u); /// assert_eq!(rc::try_unwrap(x), Ok(3u)); +/// /// let x = Rc::new(4u); /// let _y = x.clone(); /// assert_eq!(rc::try_unwrap(x), Err(Rc::new(4u))); @@ -266,18 +289,19 @@ pub fn try_unwrap(rc: Rc) -> Result> { } } -/// Returns a mutable reference to the contained value if the `Rc` has -/// unique ownership. +/// Returns a mutable reference to the contained value if the `Rc` is unique. /// -/// Returns `None` if the `Rc` does not have unique ownership. +/// Returns `None` if the `Rc` is not unique. /// /// # Example /// /// ``` /// use std::rc::{mod, Rc}; +/// /// let mut x = Rc::new(3u); /// *rc::get_mut(&mut x).unwrap() = 4u; /// assert_eq!(*x, 4u); +/// /// let _y = x.clone(); /// assert!(rc::get_mut(&mut x).is_none()); /// ``` @@ -293,11 +317,20 @@ pub fn get_mut<'a, T>(rc: &'a mut Rc) -> Option<&'a mut T> { } impl Rc { - /// Acquires a mutable pointer to the inner contents by guaranteeing that - /// the reference count is one (no sharing is possible). + /// Make a mutable reference from the given `Rc`. + /// + /// This is also referred to as a copy-on-write operation because the inner data is cloned if + /// the reference count is greater than one. + /// + /// # Examples /// - /// This is also referred to as a copy-on-write operation because the inner - /// data is cloned if the reference count is greater than one. + /// ``` + /// use std::rc::Rc; + /// + /// let mut five = Rc::new(5i); + /// + /// let mut_five = five.make_unique(); + /// ``` #[inline] #[experimental] pub fn make_unique(&mut self) -> &mut T { @@ -307,8 +340,8 @@ impl Rc { // This unsafety is ok because we're guaranteed that the pointer // returned is the *only* pointer that will ever be returned to T. Our // reference count is guaranteed to be 1 at this point, and we required - // the Rc itself to be `mut`, so we're returning the only possible - // reference to the inner data. + // the `Rc` itself to be `mut`, so we're returning the only possible + // reference to the inner value. let inner = unsafe { &mut *self._ptr }; &mut inner.value } @@ -316,7 +349,6 @@ impl Rc { #[experimental = "Deref is experimental."] impl Deref for Rc { - /// Borrows the value contained in the reference-counted pointer. #[inline(always)] fn deref(&self) -> &T { &self.inner().value @@ -326,6 +358,30 @@ impl Deref for Rc { #[unsafe_destructor] #[experimental = "Drop is experimental."] impl Drop for Rc { + /// Drops the `Rc`. + /// + /// This will decrement the strong reference count. If the strong reference count becomes zero + /// and the only other references are `Weak` ones, `drop`s the inner value. + /// + /// # Examples + /// + /// ``` + /// use std::rc::Rc; + /// + /// { + /// let five = Rc::new(5i); + /// + /// // stuff + /// + /// drop(five); // explict drop + /// } + /// { + /// let five = Rc::new(5i); + /// + /// // stuff + /// + /// } // implicit drop + /// ``` fn drop(&mut self) { unsafe { if !self._ptr.is_null() { @@ -349,6 +405,19 @@ impl Drop for Rc { #[unstable = "Clone is unstable."] impl Clone for Rc { + /// Makes a clone of the `Rc`. + /// + /// This increases the strong reference count. + /// + /// # Examples + /// + /// ``` + /// use std::rc::Rc; + /// + /// let five = Rc::new(5i); + /// + /// five.clone(); + /// ``` #[inline] fn clone(&self) -> Rc { self.inc_strong(); @@ -358,6 +427,16 @@ impl Clone for Rc { #[stable] impl Default for Rc { + /// Creates a new `Rc`, with the `Default` value for `T`. + /// + /// # Examples + /// + /// ``` + /// use std::rc::Rc; + /// use std::default::Default; + /// + /// let x: Rc = Default::default(); + /// ``` #[inline] fn default() -> Rc { Rc::new(Default::default()) @@ -366,8 +445,35 @@ impl Default for Rc { #[unstable = "PartialEq is unstable."] impl PartialEq for Rc { + /// Equality for two `Rc`s. + /// + /// Two `Rc`s are equal if their inner value are equal. + /// + /// # Examples + /// + /// ``` + /// use std::rc::Rc; + /// + /// let five = Rc::new(5i); + /// + /// five == Rc::new(5i); + /// ``` #[inline(always)] fn eq(&self, other: &Rc) -> bool { **self == **other } + + /// Inequality for two `Rc`s. + /// + /// Two `Rc`s are unequal if their inner value are unequal. + /// + /// # Examples + /// + /// ``` + /// use std::rc::Rc; + /// + /// let five = Rc::new(5i); + /// + /// five != Rc::new(5i); + /// ``` #[inline(always)] fn ne(&self, other: &Rc) -> bool { **self != **other } } @@ -377,26 +483,104 @@ impl Eq for Rc {} #[unstable = "PartialOrd is unstable."] impl PartialOrd for Rc { + /// Partial comparison for two `Rc`s. + /// + /// The two are compared by calling `partial_cmp()` on their inner values. + /// + /// # Examples + /// + /// ``` + /// use std::rc::Rc; + /// + /// let five = Rc::new(5i); + /// + /// five.partial_cmp(&Rc::new(5i)); + /// ``` #[inline(always)] fn partial_cmp(&self, other: &Rc) -> Option { (**self).partial_cmp(&**other) } + /// Less-than comparison for two `Rc`s. + /// + /// The two are compared by calling `<` on their inner values. + /// + /// # Examples + /// + /// ``` + /// use std::rc::Rc; + /// + /// let five = Rc::new(5i); + /// + /// five < Rc::new(5i); + /// ``` #[inline(always)] fn lt(&self, other: &Rc) -> bool { **self < **other } + /// 'Less-than or equal to' comparison for two `Rc`s. + /// + /// The two are compared by calling `<=` on their inner values. + /// + /// # Examples + /// + /// ``` + /// use std::rc::Rc; + /// + /// let five = Rc::new(5i); + /// + /// five <= Rc::new(5i); + /// ``` #[inline(always)] fn le(&self, other: &Rc) -> bool { **self <= **other } + /// Greater-than comparison for two `Rc`s. + /// + /// The two are compared by calling `>` on their inner values. + /// + /// # Examples + /// + /// ``` + /// use std::rc::Rc; + /// + /// let five = Rc::new(5i); + /// + /// five > Rc::new(5i); + /// ``` #[inline(always)] fn gt(&self, other: &Rc) -> bool { **self > **other } + /// 'Greater-than or equal to' comparison for two `Rc`s. + /// + /// The two are compared by calling `>=` on their inner values. + /// + /// # Examples + /// + /// ``` + /// use std::rc::Rc; + /// + /// let five = Rc::new(5i); + /// + /// five >= Rc::new(5i); + /// ``` #[inline(always)] fn ge(&self, other: &Rc) -> bool { **self >= **other } } #[unstable = "Ord is unstable."] impl Ord for Rc { + /// Comparison for two `Rc`s. + /// + /// The two are compared by calling `cmp()` on their inner values. + /// + /// # Examples + /// + /// ``` + /// use std::rc::Rc; + /// + /// let five = Rc::new(5i); + /// + /// five.partial_cmp(&Rc::new(5i)); + /// ``` #[inline] fn cmp(&self, other: &Rc) -> Ordering { (**self).cmp(&**other) } } @@ -408,7 +592,11 @@ impl fmt::Show for Rc { } } -/// A weak reference to a reference-counted pointer. +/// A weak version of `Rc`. +/// +/// Weak references do not count when determining if the inner value should be dropped. +/// +/// See the [module level documentation](../index.html) for more. #[unsafe_no_drop_flag] #[experimental = "Weak pointers may not belong in this module."] pub struct Weak { @@ -423,8 +611,21 @@ pub struct Weak { impl Weak { /// Upgrades a weak reference to a strong reference. /// - /// Returns `None` if there were no strong references and the data was - /// destroyed. + /// Upgrades the `Weak` reference to an `Rc`, if possible. + /// + /// Returns `None` if there were no strong references and the data was destroyed. + /// + /// # Examples + /// + /// ``` + /// use std::rc::Rc; + /// + /// let five = Rc::new(5i); + /// + /// let weak_five = five.downgrade(); + /// + /// let strong_five: Option> = weak_five.upgrade(); + /// ``` pub fn upgrade(&self) -> Option> { if self.strong() == 0 { None @@ -438,6 +639,31 @@ impl Weak { #[unsafe_destructor] #[experimental = "Weak pointers may not belong in this module."] impl Drop for Weak { + /// Drops the `Weak`. + /// + /// This will decrement the weak reference count. + /// + /// # Examples + /// + /// ``` + /// use std::rc::Rc; + /// + /// { + /// let five = Rc::new(5i); + /// let weak_five = five.downgrade(); + /// + /// // stuff + /// + /// drop(weak_five); // explict drop + /// } + /// { + /// let five = Rc::new(5i); + /// let weak_five = five.downgrade(); + /// + /// // stuff + /// + /// } // implicit drop + /// ``` fn drop(&mut self) { unsafe { if !self._ptr.is_null() { @@ -455,6 +681,19 @@ impl Drop for Weak { #[experimental = "Weak pointers may not belong in this module."] impl Clone for Weak { + /// Makes a clone of the `Weak`. + /// + /// This increases the weak reference count. + /// + /// # Examples + /// + /// ``` + /// use std::rc::Rc; + /// + /// let weak_five = Rc::new(5i).downgrade(); + /// + /// weak_five.clone(); + /// ``` #[inline] fn clone(&self) -> Weak { self.inc_weak();