1
Fork 0

Rework Rc for FCP of #27718

* Add `Rc::would_unwrap(&Self) -> bool` to introspect whether try_unwrap would succeed,
  because it's destructive (unlike get_mut).
* Move `rc.downgrade()` to `Rc::downgrade(&Self)` per conventions.
* Deprecate `Rc::weak_count` and `Rc::strong_count` for questionable utility.
* Deprecate `Rc::is_unique` for questionable semantics (there are two kinds of
  uniqueness with Weak pointers in play).
* Rename `rc.make_unique()` to `Rc::make_mut(&mut Self)` per conventions, to
  avoid uniqueness terminology, and to clarify the relation to `Rc::get_mut`.
This commit is contained in:
Alexis Beingessner 2015-08-12 12:00:46 -07:00
parent aca2057ed5
commit 635f7360b6

View file

@ -8,6 +8,9 @@
// option. This file may not be copied, modified, or distributed // option. This file may not be copied, modified, or distributed
// except according to those terms. // except according to those terms.
// FIXME(27718): rc_counts stuff is useful internally, but was previously public
#![allow(deprecated)]
//! Thread-local reference-counted boxes (the `Rc<T>` type). //! Thread-local reference-counted boxes (the `Rc<T>` type).
//! //!
//! The `Rc<T>` type provides shared ownership of an immutable value. //! The `Rc<T>` type provides shared ownership of an immutable value.
@ -126,8 +129,8 @@
//! //!
//! // Add the Gadgets to their Owner. To do this we mutably borrow from //! // Add the Gadgets to their Owner. To do this we mutably borrow from
//! // the RefCell holding the Owner's Gadgets. //! // the RefCell holding the Owner's Gadgets.
//! gadget_owner.gadgets.borrow_mut().push(gadget1.clone().downgrade()); //! gadget_owner.gadgets.borrow_mut().push(Rc::downgrade(&gadget1));
//! gadget_owner.gadgets.borrow_mut().push(gadget2.clone().downgrade()); //! gadget_owner.gadgets.borrow_mut().push(Rc::downgrade(&gadget2));
//! //!
//! // Iterate over our Gadgets, printing their details out //! // Iterate over our Gadgets, printing their details out
//! for gadget_opt in gadget_owner.gadgets.borrow().iter() { //! for gadget_opt in gadget_owner.gadgets.borrow().iter() {
@ -161,7 +164,7 @@ use core::fmt;
use core::hash::{Hasher, Hash}; use core::hash::{Hasher, Hash};
use core::intrinsics::{assume, drop_in_place, abort}; use core::intrinsics::{assume, drop_in_place, abort};
use core::marker::{self, Unsize}; use core::marker::{self, Unsize};
use core::mem::{self, align_of, size_of, align_of_val, size_of_val, forget}; use core::mem::{self, align_of_val, size_of_val, forget};
use core::nonzero::NonZero; use core::nonzero::NonZero;
use core::ops::{CoerceUnsized, Deref}; use core::ops::{CoerceUnsized, Deref};
use core::ptr; use core::ptr;
@ -218,10 +221,10 @@ impl<T> Rc<T> {
} }
} }
/// Unwraps the contained value if the `Rc<T>` is unique. /// Unwraps the contained value if the `Rc<T>` has only one strong reference.
/// This will succeed even if there are outstanding weak references.
/// ///
/// If the `Rc<T>` is not unique, an `Err` is returned with the same /// Otherwise, an `Err` is returned with the same `Rc<T>`.
/// `Rc<T>`.
/// ///
/// # Examples /// # Examples
/// ///
@ -238,22 +241,32 @@ impl<T> Rc<T> {
/// assert_eq!(Rc::try_unwrap(x), Err(Rc::new(4))); /// assert_eq!(Rc::try_unwrap(x), Err(Rc::new(4)));
/// ``` /// ```
#[inline] #[inline]
#[unstable(feature = "rc_unique", issue = "27718")] #[unstable(feature = "rc_unique", reason= "needs FCP", issue = "27718")]
pub fn try_unwrap(rc: Rc<T>) -> Result<T, Rc<T>> { pub fn try_unwrap(this: Self) -> Result<T, Self> {
if Rc::is_unique(&rc) { if Rc::would_unwrap(&this) {
unsafe { unsafe {
let val = ptr::read(&*rc); // copy the contained object let val = ptr::read(&*this); // copy the contained object
// destruct the box and skip our Drop
// we can ignore the refcounts because we know we're unique // Indicate to Weaks that they can't be promoted by decrememting
deallocate(*rc._ptr as *mut u8, size_of::<RcBox<T>>(), // the strong count, and then remove the implicit "strong weak"
align_of::<RcBox<T>>()); // pointer while also handling drop logic by just crafting a
forget(rc); // fake Weak.
this.dec_strong();
let _weak = Weak { _ptr: this._ptr };
forget(this);
Ok(val) Ok(val)
} }
} else { } else {
Err(rc) Err(this)
} }
} }
/// Checks if `Rc::try_unwrap` would return `Ok`.
#[unstable(feature = "rc_would_unwrap", reason = "just added for niche usecase",
issue = "27718")]
pub fn would_unwrap(this: &Self) -> bool {
Rc::strong_count(&this) == 1
}
} }
impl<T: ?Sized> Rc<T> { impl<T: ?Sized> Rc<T> {
@ -268,25 +281,25 @@ impl<T: ?Sized> Rc<T> {
/// ///
/// let five = Rc::new(5); /// let five = Rc::new(5);
/// ///
/// let weak_five = five.downgrade(); /// let weak_five = Rc::downgrade(&five);
/// ``` /// ```
#[unstable(feature = "rc_weak", #[unstable(feature = "rc_weak", reason = "needs FCP", issue = "27718")]
reason = "Weak pointers may not belong in this module", pub fn downgrade(this: &Self) -> Weak<T> {
issue = "27718")] this.inc_weak();
pub fn downgrade(&self) -> Weak<T> { Weak { _ptr: this._ptr }
self.inc_weak();
Weak { _ptr: self._ptr }
} }
/// Get the number of weak references to this value. /// Get the number of weak references to this value.
#[inline] #[inline]
#[unstable(feature = "rc_counts", issue = "27718")] #[unstable(feature = "rc_counts", reason = "not clearly useful", issue = "27718")]
pub fn weak_count(this: &Rc<T>) -> usize { this.weak() - 1 } #[deprecated(since = "1.4.0", reason = "not clearly useful")]
pub fn weak_count(this: &Self) -> usize { this.weak() - 1 }
/// Get the number of strong references to this value. /// Get the number of strong references to this value.
#[inline] #[inline]
#[unstable(feature = "rc_counts", issue= "27718")] #[unstable(feature = "rc_counts", reason = "not clearly useful", issue = "27718")]
pub fn strong_count(this: &Rc<T>) -> usize { this.strong() } #[deprecated(since = "1.4.0", reason = "not clearly useful")]
pub fn strong_count(this: &Self) -> usize { this.strong() }
/// Returns true if there are no other `Rc` or `Weak<T>` values that share /// Returns true if there are no other `Rc` or `Weak<T>` values that share
/// the same inner value. /// the same inner value.
@ -294,7 +307,7 @@ impl<T: ?Sized> Rc<T> {
/// # Examples /// # Examples
/// ///
/// ``` /// ```
/// #![feature(rc_unique)] /// #![feature(rc_counts)]
/// ///
/// use std::rc::Rc; /// use std::rc::Rc;
/// ///
@ -303,13 +316,14 @@ impl<T: ?Sized> Rc<T> {
/// assert!(Rc::is_unique(&five)); /// assert!(Rc::is_unique(&five));
/// ``` /// ```
#[inline] #[inline]
#[unstable(feature = "rc_unique", issue = "27718")] #[unstable(feature = "rc_counts", reason = "uniqueness has unclear meaning", issue = "27718")]
pub fn is_unique(rc: &Rc<T>) -> bool { #[deprecated(since = "1.4.0", reason = "uniqueness has unclear meaning")]
Rc::weak_count(rc) == 0 && Rc::strong_count(rc) == 1 pub fn is_unique(this: &Self) -> bool {
Rc::weak_count(this) == 0 && Rc::strong_count(this) == 1
} }
/// Returns a mutable reference to the contained value if the `Rc<T>` is /// Returns a mutable reference to the contained value if the `Rc<T>` has
/// unique. /// one strong reference and no weak references.
/// ///
/// Returns `None` if the `Rc<T>` is not unique. /// Returns `None` if the `Rc<T>` is not unique.
/// ///
@ -328,10 +342,10 @@ impl<T: ?Sized> Rc<T> {
/// assert!(Rc::get_mut(&mut x).is_none()); /// assert!(Rc::get_mut(&mut x).is_none());
/// ``` /// ```
#[inline] #[inline]
#[unstable(feature = "rc_unique", issue = "27718")] #[unstable(feature = "rc_unique", reason = "needs FCP", issue = "27718")]
pub fn get_mut(rc: &mut Rc<T>) -> Option<&mut T> { pub fn get_mut(this: &mut Self) -> Option<&mut T> {
if Rc::is_unique(rc) { if Rc::is_unique(this) {
let inner = unsafe { &mut **rc._ptr }; let inner = unsafe { &mut **this._ptr };
Some(&mut inner.value) Some(&mut inner.value)
} else { } else {
None None
@ -340,34 +354,62 @@ impl<T: ?Sized> Rc<T> {
} }
impl<T: Clone> Rc<T> { impl<T: Clone> Rc<T> {
/// Make a mutable reference from the given `Rc<T>`. #[inline]
#[unstable(feature = "rc_unique", reason = "renamed to Rc::make_mut", issue = "27718")]
#[deprecated(since = "1.4.0", reason = "renamed to Rc::make_mut")]
pub fn make_unique(&mut self) -> &mut T {
Rc::make_mut(self)
}
/// Make a mutable reference into the given `Rc<T>` by cloning the inner
/// data if the `Rc<T>` doesn't have one strong reference and no weak
/// references.
/// ///
/// This is also referred to as a copy-on-write operation because the inner /// This is also referred to as a copy-on-write.
/// data is cloned if the reference count is greater than one.
/// ///
/// # Examples /// # Examples
/// ///
/// ``` /// ```
/// #![feature(rc_unique)] /// #![feature(rc_unique)]
///
/// use std::rc::Rc; /// use std::rc::Rc;
/// ///
/// let mut five = Rc::new(5); /// 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
/// *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
///
/// // Note: data and other_data now point to different numbers
/// assert_eq!(*data, 8);
/// assert_eq!(*other_data, 12);
/// ///
/// let mut_five = five.make_unique();
/// ``` /// ```
#[inline] #[inline]
#[unstable(feature = "rc_unique", issue = "27718")] #[unstable(feature = "rc_unique", reason = "needs FCP", issue = "27718")]
pub fn make_unique(&mut self) -> &mut T { pub fn make_mut(this: &mut Self) -> &mut T {
if !Rc::is_unique(self) { if Rc::strong_count(this) != 1 {
*self = Rc::new((**self).clone()) // Gotta clone the data, there are other Rcs
*this = Rc::new((**this).clone())
} else if Rc::weak_count(this) != 0 {
// Can just steal the data, all that's left is Weaks
unsafe {
let mut swap = Rc::new(ptr::read(&(**this._ptr).value));
mem::swap(this, &mut swap);
swap.dec_strong();
// Remove implicit strong-weak ref (no need to craft a fake
// Weak here -- we know other Weaks can clean up for us)
swap.dec_weak();
forget(swap);
}
} }
// This unsafety is ok because we're guaranteed that the pointer // This unsafety is ok because we're guaranteed that the pointer
// returned is the *only* pointer that will ever be returned to T. Our // 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 // reference count is guaranteed to be 1 at this point, and we required
// the `Rc<T>` itself to be `mut`, so we're returning the only possible // the `Rc<T>` itself to be `mut`, so we're returning the only possible
// reference to the inner value. // reference to the inner value.
let inner = unsafe { &mut **self._ptr }; let inner = unsafe { &mut **this._ptr };
&mut inner.value &mut inner.value
} }
} }
@ -413,7 +455,7 @@ impl<T: ?Sized> Drop for Rc<T> {
unsafe { unsafe {
let ptr = *self._ptr; let ptr = *self._ptr;
if !(*(&ptr as *const _ as *const *const ())).is_null() && if !(*(&ptr as *const _ as *const *const ())).is_null() &&
ptr as *const () as usize != mem::POST_DROP_USIZE { ptr as *const () as usize != mem::POST_DROP_USIZE {
self.dec_strong(); self.dec_strong();
if self.strong() == 0 { if self.strong() == 0 {
// destroy the contained object // destroy the contained object
@ -653,9 +695,7 @@ impl<T> fmt::Pointer for Rc<T> {
/// ///
/// See the [module level documentation](./index.html) for more. /// See the [module level documentation](./index.html) for more.
#[unsafe_no_drop_flag] #[unsafe_no_drop_flag]
#[unstable(feature = "rc_weak", #[unstable(feature = "rc_weak", reason = "needs FCP", issue = "27718")]
reason = "Weak pointers may not belong in this module.",
issue = "27718")]
pub struct Weak<T: ?Sized> { pub struct Weak<T: ?Sized> {
// FIXME #12808: strange names to try to avoid interfering with // FIXME #12808: strange names to try to avoid interfering with
// field accesses of the contained type via Deref // field accesses of the contained type via Deref
@ -667,11 +707,7 @@ impl<T: ?Sized> !marker::Sync for Weak<T> {}
impl<T: ?Sized+Unsize<U>, U: ?Sized> CoerceUnsized<Weak<U>> for Weak<T> {} impl<T: ?Sized+Unsize<U>, U: ?Sized> CoerceUnsized<Weak<U>> for Weak<T> {}
#[unstable(feature = "rc_weak",
reason = "Weak pointers may not belong in this module.",
issue = "27718")]
impl<T: ?Sized> Weak<T> { impl<T: ?Sized> Weak<T> {
/// Upgrades a weak reference to a strong reference. /// Upgrades a weak reference to a strong reference.
/// ///
/// Upgrades the `Weak<T>` reference to an `Rc<T>`, if possible. /// Upgrades the `Weak<T>` reference to an `Rc<T>`, if possible.
@ -688,10 +724,11 @@ impl<T: ?Sized> Weak<T> {
/// ///
/// let five = Rc::new(5); /// let five = Rc::new(5);
/// ///
/// let weak_five = five.downgrade(); /// let weak_five = Rc::downgrade(&five);
/// ///
/// let strong_five: Option<Rc<_>> = weak_five.upgrade(); /// let strong_five: Option<Rc<_>> = weak_five.upgrade();
/// ``` /// ```
#[unstable(feature = "rc_weak", reason = "needs FCP", issue = "27718")]
pub fn upgrade(&self) -> Option<Rc<T>> { pub fn upgrade(&self) -> Option<Rc<T>> {
if self.strong() == 0 { if self.strong() == 0 {
None None
@ -717,7 +754,7 @@ impl<T: ?Sized> Drop for Weak<T> {
/// ///
/// { /// {
/// let five = Rc::new(5); /// let five = Rc::new(5);
/// let weak_five = five.downgrade(); /// let weak_five = Rc::downgrade(&five);
/// ///
/// // stuff /// // stuff
/// ///
@ -725,7 +762,7 @@ impl<T: ?Sized> Drop for Weak<T> {
/// } /// }
/// { /// {
/// let five = Rc::new(5); /// let five = Rc::new(5);
/// let weak_five = five.downgrade(); /// let weak_five = Rc::downgrade(&five);
/// ///
/// // stuff /// // stuff
/// ///
@ -735,7 +772,7 @@ impl<T: ?Sized> Drop for Weak<T> {
unsafe { unsafe {
let ptr = *self._ptr; let ptr = *self._ptr;
if !(*(&ptr as *const _ as *const *const ())).is_null() && if !(*(&ptr as *const _ as *const *const ())).is_null() &&
ptr as *const () as usize != mem::POST_DROP_USIZE { ptr as *const () as usize != mem::POST_DROP_USIZE {
self.dec_weak(); self.dec_weak();
// the weak count starts at 1, and will only go to zero if all // the weak count starts at 1, and will only go to zero if all
// the strong pointers have disappeared. // the strong pointers have disappeared.
@ -748,9 +785,7 @@ impl<T: ?Sized> Drop for Weak<T> {
} }
} }
#[unstable(feature = "rc_weak", #[unstable(feature = "rc_weak", reason = "needs FCP", issue = "27718")]
reason = "Weak pointers may not belong in this module.",
issue = "27718")]
impl<T: ?Sized> Clone for Weak<T> { impl<T: ?Sized> Clone for Weak<T> {
/// Makes a clone of the `Weak<T>`. /// Makes a clone of the `Weak<T>`.
@ -764,7 +799,7 @@ impl<T: ?Sized> Clone for Weak<T> {
/// ///
/// use std::rc::Rc; /// use std::rc::Rc;
/// ///
/// let weak_five = Rc::new(5).downgrade(); /// let weak_five = Rc::downgrade(&Rc::new(5));
/// ///
/// weak_five.clone(); /// weak_five.clone();
/// ``` /// ```
@ -888,14 +923,14 @@ mod tests {
#[test] #[test]
fn test_live() { fn test_live() {
let x = Rc::new(5); let x = Rc::new(5);
let y = x.downgrade(); let y = Rc::downgrade(&x);
assert!(y.upgrade().is_some()); assert!(y.upgrade().is_some());
} }
#[test] #[test]
fn test_dead() { fn test_dead() {
let x = Rc::new(5); let x = Rc::new(5);
let y = x.downgrade(); let y = Rc::downgrade(&x);
drop(x); drop(x);
assert!(y.upgrade().is_none()); assert!(y.upgrade().is_none());
} }
@ -907,7 +942,7 @@ mod tests {
} }
let a = Rc::new(Cycle { x: RefCell::new(None) }); let a = Rc::new(Cycle { x: RefCell::new(None) });
let b = a.clone().downgrade(); let b = Rc::downgrade(&a.clone());
*a.x.borrow_mut() = Some(b); *a.x.borrow_mut() = Some(b);
// hopefully we don't double-free (or leak)... // hopefully we don't double-free (or leak)...
@ -921,7 +956,7 @@ mod tests {
assert!(!Rc::is_unique(&x)); assert!(!Rc::is_unique(&x));
drop(y); drop(y);
assert!(Rc::is_unique(&x)); assert!(Rc::is_unique(&x));
let w = x.downgrade(); let w = Rc::downgrade(&x);
assert!(!Rc::is_unique(&x)); assert!(!Rc::is_unique(&x));
drop(w); drop(w);
assert!(Rc::is_unique(&x)); assert!(Rc::is_unique(&x));
@ -931,7 +966,7 @@ mod tests {
fn test_strong_count() { fn test_strong_count() {
let a = Rc::new(0u32); let a = Rc::new(0u32);
assert!(Rc::strong_count(&a) == 1); assert!(Rc::strong_count(&a) == 1);
let w = a.downgrade(); let w = Rc::downgrade(&a);
assert!(Rc::strong_count(&a) == 1); assert!(Rc::strong_count(&a) == 1);
let b = w.upgrade().expect("upgrade of live rc failed"); let b = w.upgrade().expect("upgrade of live rc failed");
assert!(Rc::strong_count(&b) == 2); assert!(Rc::strong_count(&b) == 2);
@ -949,7 +984,7 @@ mod tests {
let a = Rc::new(0u32); let a = Rc::new(0u32);
assert!(Rc::strong_count(&a) == 1); assert!(Rc::strong_count(&a) == 1);
assert!(Rc::weak_count(&a) == 0); assert!(Rc::weak_count(&a) == 0);
let w = a.downgrade(); let w = Rc::downgrade(&a);
assert!(Rc::strong_count(&a) == 1); assert!(Rc::strong_count(&a) == 1);
assert!(Rc::weak_count(&a) == 1); assert!(Rc::weak_count(&a) == 1);
drop(w); drop(w);
@ -969,8 +1004,8 @@ mod tests {
let _y = x.clone(); let _y = x.clone();
assert_eq!(Rc::try_unwrap(x), Err(Rc::new(4))); assert_eq!(Rc::try_unwrap(x), Err(Rc::new(4)));
let x = Rc::new(5); let x = Rc::new(5);
let _w = x.downgrade(); let _w = Rc::downgrade(&x);
assert_eq!(Rc::try_unwrap(x), Err(Rc::new(5))); assert_eq!(Rc::try_unwrap(x), Ok(5));
} }
#[test] #[test]
@ -982,7 +1017,7 @@ mod tests {
assert!(Rc::get_mut(&mut x).is_none()); assert!(Rc::get_mut(&mut x).is_none());
drop(y); drop(y);
assert!(Rc::get_mut(&mut x).is_some()); assert!(Rc::get_mut(&mut x).is_some());
let _w = x.downgrade(); let _w = Rc::downgrade(&x);
assert!(Rc::get_mut(&mut x).is_none()); assert!(Rc::get_mut(&mut x).is_none());
} }
@ -992,13 +1027,13 @@ mod tests {
let mut cow1 = cow0.clone(); let mut cow1 = cow0.clone();
let mut cow2 = cow1.clone(); let mut cow2 = cow1.clone();
assert!(75 == *cow0.make_unique()); assert!(75 == *Rc::make_mut(&mut cow0));
assert!(75 == *cow1.make_unique()); assert!(75 == *Rc::make_mut(&mut cow1));
assert!(75 == *cow2.make_unique()); assert!(75 == *Rc::make_mut(&mut cow2));
*cow0.make_unique() += 1; *Rc::make_mut(&mut cow0) += 1;
*cow1.make_unique() += 2; *Rc::make_mut(&mut cow1) += 2;
*cow2.make_unique() += 3; *Rc::make_mut(&mut cow2) += 3;
assert!(76 == *cow0); assert!(76 == *cow0);
assert!(77 == *cow1); assert!(77 == *cow1);
@ -1020,7 +1055,7 @@ mod tests {
assert!(75 == *cow1); assert!(75 == *cow1);
assert!(75 == *cow2); assert!(75 == *cow2);
*cow0.make_unique() += 1; *Rc::make_mut(&mut cow0) += 1;
assert!(76 == *cow0); assert!(76 == *cow0);
assert!(75 == *cow1); assert!(75 == *cow1);
@ -1036,12 +1071,12 @@ mod tests {
#[test] #[test]
fn test_cowrc_clone_weak() { fn test_cowrc_clone_weak() {
let mut cow0 = Rc::new(75); let mut cow0 = Rc::new(75);
let cow1_weak = cow0.downgrade(); let cow1_weak = Rc::downgrade(&cow0);
assert!(75 == *cow0); assert!(75 == *cow0);
assert!(75 == *cow1_weak.upgrade().unwrap()); assert!(75 == *cow1_weak.upgrade().unwrap());
*cow0.make_unique() += 1; *Rc::make_mut(&mut cow0) += 1;
assert!(76 == *cow0); assert!(76 == *cow0);
assert!(cow1_weak.upgrade().is_none()); assert!(cow1_weak.upgrade().is_none());