Struct drc::Drc

pub struct Drc<T> where
    T: ?Sized,  { /* fields omitted */ }

A single-threaded reference-counting pointer with the special ability to be converted into an Arc. 'Drc' stands for 'Dynamically Reference Counted'.

See the crate-level documentation for more details.

The inherent methods of Drc are all associated functions, which means you have to call them as e.g. Drc::get_mut(&mut value) instead value.get_mut(). This avoids conflict with methods of the inner type T.

Methods

impl<T> Drc<T>

pub fn new(value: T) -> Drc<T>

Constructs a new Drc.

Examples

use drc::Drc;

let five = Drc::new(5);

impl<T> Drc<T> where     T: ?Sized,

pub fn detach(this: &Drc<T>) -> Arc<T>

Clones the internal Arc (incrementing the atomic strong reference count) so that the shared state can be referenced on another thread. Then, returns this newly cloned Arc. To convert the Arc back into a Drc (with a separate local state), use from.

Examples

use drc::Drc;

let five = Drc::new(5);
let arc_five = Drc::detach(&five);

assert_eq!(*five, *arc_five);

pub fn separate(this: &Drc<T>) -> Drc<T>

Clone the internal Arc (incrementing the atomic strong reference count), create new local reference counts, and associate a new Drc to these new reference counts.

This is not too useful outside of testing, but it is provided as a way to simulate the intended process of sending an Arc across a thread and converting it back into a Drc without the need for multiple method calls.

Drc::linked will not evaluate true for separated values, though Drc::ptr_eq will.

Examples

use drc::Drc;

let five = Drc::new(5);
let separate_five = Drc::separate(&five);

assert!(Drc::ptr_eq(&five, &separate_five));
assert!(!Drc::linked(&five, &separate_five));

impl<T> Drc<T>

pub fn try_unwrap(this: Drc<T>) -> Result<T, Drc<T>>

Returns the contained value, if the Arc associated with the Drc has exactly one strong reference.

Otherwise, an Err will be returned with the same Drc that was passed in.

This will succeed even if there are outstanding weak references.

Examples

use drc::Drc;

// The `Drc` here is the only strong reference to 3, so it is successfully
// unwrapped.
let x = Drc::new(3);
assert_eq!(Drc::try_unwrap(x), Ok(3));

// There are two `Drc` strong references to 4, so it is not successfully
// unwrapped.
let x = Drc::new(4);
let _y = Drc::clone(&x);
assert_eq!(*Drc::try_unwrap(x).unwrap_err(), 4);

// There is a `Drc` and an `Arc` strong reference to 5, so it is not
// sucessfully unwrapped.
let x = Drc::new(5);
let _y = Drc::detach(&x);
assert_eq!(*Drc::try_unwrap(x).unwrap_err(), 5);

impl<T> Drc<T> where     T: ?Sized,

pub fn downgrade(this: &Drc<T>) -> Weak<T>

Creates a new Weak pointer to this value.

Examples

use drc::Drc;

let five = Drc::new(5);

let weak_five = Drc::downgrade(&five);

pub fn weak_count(this: &Drc<T>, local: bool) -> usize

If local, gets the number of Weak (Drc) pointers associated with the same internal Arc. Otherwise, gets the number of Weak (Arc) pointers associated associated with the value.

It's worth noting that neither of these values are the total counts of weak pointers associated with a given value. Using a local value of false will return the number of Drc sets containing at least one weak pointer plus the number of Arc weak pointers. This is not equivalent to the sum of the total counts for each type of weak pointer.

Examples

use drc::Drc;
use std::sync::Arc;

let five = Drc::new(5);
let _weak_five_a = Drc::downgrade(&five);
let _weak_five_b = Drc::downgrade(&five);
let _weak_five_c = Drc::downgrade(&five);

// No contribution because no weak pointers.
let _separate_five = Drc::separate(&five);

// detached_five is an Arc that points to the same value.
let detached_five = Drc::detach(&five);
let _weak_detached_five = Arc::downgrade(&detached_five);

// 3 values:
// _weak_five_a, _weak_five_b, _weak_five_c
assert_eq!(3, Drc::weak_count(&five, true));

// 2 values:
// (_weak_five_a, _weak_five_b, _weak_five_c), _weak_detached_five
assert_eq!(2, Drc::weak_count(&five, false));

pub fn strong_count(this: &Drc<T>, local: bool) -> usize

If local, gets the number of Drc pointers associated with the same internal Arc. Otherwise, gets the number of Arcs associated with the value.

It's worth noting that neither of these values are the total counts of strong pointers associated with a given value. Using a local value of false will return the number of Drc sets containing at least one strong pointer plus the number of Arc pointers. This is not equivalent to the sum of the total counts for each type of strong pointer.

Examples

use drc::Drc;
use std::sync::Arc;

let five = Drc::new(5);
let _also_five = Drc::clone(&five);
let _still_five = Drc::clone(&five);

// No contribution because no strong pointer.
let _weak_separate_five = {
    let separate_five = Drc::separate(&five);
    Drc::downgrade(&separate_five)
};

// This is basically a glorified Arc, basically (Arc,)
let _strong_separate_five = Drc::separate(&five);

// detached_five is an Arc that points to the same value.
let detached_five = Drc::detach(&five);
let _also_detached_five = Arc::clone(&detached_five);

// 3 values:
// five, _also_five, _still_five
assert_eq!(3, Drc::strong_count(&five, true));

// 4 values:
// (five, _also_five, _still_five), (_strong_separate_five,), detached_five,
//     _also_detached_five
assert_eq!(4, Drc::strong_count(&five, false));

pub fn get_mut(this: &mut Drc<T>) -> Option<&mut T>

Returns a mutable reference to the inner value, if there are no other Drcs, Arcs, weak Drcs, or weak Arcs to the same value.

Returns None otherwise, because it is not safe to mutate a shared value.

See also make_mut, which will clone the inner value when it's shared.

Examples

use drc::Drc;

let mut x = Drc::new(3);
*Drc::get_mut(&mut x).unwrap() = 4;
assert_eq!(*x, 4);

let _y = Drc::clone(&x);
assert!(Drc::get_mut(&mut x).is_none());

pub fn ptr_eq(this: &Drc<T>, other: &Drc<T>) -> bool

Returns true if two Drcs point to the same value (not just values that compare as equal). Note that as long as the value is the same, association to the same Arc is not necessary.

Contrast with linked, which checks if two Drcs are associated with the same Arc (i.e. they were cloned from the same Drc without detachment or becoming separate).

Compare with arc_ptr_eq, which applies the same check for the value on a Drc and Arc.

Examples

use drc::Drc;

let five = Drc::new(5);

// Associated to same `Arc`.
let same_five = Drc::clone(&five);

// Associated to different `Arc` but same value.
let separate_five = Drc::separate(&five);

// A detached and converted `Drc` is the same as a separated `Drc`, so
// this is also associated to a different `Arc` but same value.
let detached_five = Drc::from(Drc::detach(&five));

// An equal value located at a different memory address.
let other_five = Drc::new(5);

assert!(Drc::ptr_eq(&five, &same_five));
assert!(Drc::ptr_eq(&five, &separate_five));
assert!(Drc::ptr_eq(&five, &detached_five));
assert!(!Drc::ptr_eq(&five, &other_five));

pub fn arc_ptr_eq(this: &Drc<T>, other: &Arc<T>) -> bool

Returns true if a Drc and an Arc points to the same value (not just values that compare as equal). Note that as long as the value is the same, association of the passed Drc to the Arc is not necessary (and is in fact impossible, as a reference to the internal Arc cannot be retrieved externally).

Contrast with linked, which checks if two Drcs are associated with the same Arc (i.e. they were cloned from the same Drc without detachment or becoming separate).

Compare with ptr_eq, which applies the same check for the value on two Drcs.

Examples

use drc::Drc;
use std::sync::Arc;

let five = Drc::new(5);

// Points to the same value. This is an `Arc`.
let detached_five = Drc::detach(&five);

// Points to an equal value located at a different memory address.
let other_five = Arc::new(5);

assert!(Drc::arc_ptr_eq(&five, &detached_five));
assert!(!Drc::arc_ptr_eq(&five, &other_five));

pub fn linked(this: &Drc<T>, other: &Drc<T>) -> bool

Returns true if two Drcs are associated with the same Arc (i.e. they were cloned from the same Drc without detachment or becoming separate).

Contrast with ptr_eq or arc_ptr_eq, which check if two Drcs or a Drc and an Arc (respectively) point to the same value, regardless of whether the internal Arc is the same (which is of course impossible in arc_ptr_eq's case, as a reference to the internal Arc cannot be retrieved externally).

Although it was just stated that an internal Arc cannot be retrieved externally, it's worth explicitly noting that no analogue of arc_ptr_eq exists for linked because a reference to the "linked" Arc simply cannot be retrieved (Drc::from(arc) takes ownership of the Arc).

Examples

use drc::Drc;

let five = Drc::new(5);

// Associated to same `Arc`.
let same_five = Drc::clone(&five);

// Associated to different `Arc` but same value.
let separate_five = Drc::separate(&five);

// A detached and converted `Drc` is the same as a separated `Drc`, so
// this is also associated to a different `Arc` but same value.
let detached_five = Drc::from(Drc::detach(&five));

// An equal value located at a different memory address.
let other_five = Drc::new(5);

assert!(Drc::linked(&five, &same_five));
assert!(!Drc::linked(&five, &separate_five));
assert!(!Drc::linked(&five, &detached_five));
assert!(!Drc::linked(&five, &other_five));

impl<T> Drc<T> where     T: Clone,

pub fn make_mut(this: &mut Drc<T>) -> &mut T

Makes a mutable reference into the given Drc.

If there are other Drcs, Arcs, weak Drcs, or weak Arcs to the same value, then make_mut will invoke clone on the inner value to ensure unique ownership. This is also referred to as clone-on-write.

See also get_mut, which will fail rather than cloning.

Examples

use drc::Drc;

let mut data = Drc::new(5);

*Drc::make_mut(&mut data) += 1; // Won't clone anything
let mut other_data = Drc::clone(&data); // Won't clone inner data
*Drc::make_mut(&mut data) += 1; // Clones inner data
*Drc::make_mut(&mut data) += 1; // Won't clone anything
*Drc::make_mut(&mut other_data) *= 2; // Won't clone anything
let mut detached_data = Drc::detach(&other_data); // Won't clone inner data
*Drc::make_mut(&mut other_data) += 1; // Clones inner data
*Drc::make_mut(&mut other_data) += 2; // Won't clone anything

// Now `data`, `other_data`, and `detached_data` all point to different values.
assert_eq!(*data, 8);
assert_eq!(*other_data, 15);
assert_eq!(*detached_data, 12);

Trait Implementations

impl<T> Clone for Drc<T> where     T: ?Sized,

fn clone(&self) -> Drc<T>

Makes a clone of the Drc pointer.

This creates another pointer to the same inner value and associated with the same contained Arc. This increases the local strong reference count, but does not touch the Arc at all.

Examples

use drc::Drc;

let five = Drc::new(5);

let same_five = Drc::clone(&five);

// `five` and `same_five` share the same `Arc`.
assert!(Drc::linked(&five, &same_five));

// Local strong reference count of 2:
// `five`, `same_five`
assert_eq!(2, Drc::strong_count(&five, true));

// `Arc` strong reference count of 1:
// (`five`, `same_five`)
assert_eq!(1, Drc::strong_count(&five, false));

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T> Drop for Drc<T> where     T: ?Sized,

fn drop(&mut self)

Drops the Drc.

This will decrement the local strong reference count. In the case that this is the last Drc associated with the inner Arc (i.e. the local strong reference count reaches zero), the inner Arc is dropped too.

A local Weak pointer may still exist, and assuming the value still persists within the Arc's innards, said local Weak pointer might still be upgradeable even in the case that this is the last local Drc. In that case, the stored weak Arc will be upgraded to repopulate the inner Arc.

Examples

use drc::Drc;

struct Foo;

impl Drop for Foo {
    fn drop(&mut self) {
        println!("dropped!");
    }
}

let foo = Drc::new(Foo);
let foo2 = Drc::clone(&foo);

drop(foo); // Doesn't print anything
drop(foo2); // Prints "dropped!"

impl<T> AsRef<T> for Drc<T> where     T: ?Sized,

fn as_ref(&self) -> &T

Performs the conversion.

impl<T> Borrow<T> for Drc<T> where     T: ?Sized,

fn borrow(&self) -> &T

Immutably borrows from an owned value.

impl<T> Default for Drc<T> where     T: Default,

fn default() -> Drc<T>

Creates a new Drc<T>, with the Default value for T.

Examples

use drc::Drc;

let x: Drc<i32> = Default::default();
assert_eq!(*x, 0);

impl<T> Deref for Drc<T> where     T: ?Sized,

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &T

Dereferences the value.

impl<T: ?Sized> Eq for Drc<T> where     T: Eq,

impl From<CString> for Drc<CStr>

fn from(c_string: CString) -> Drc<CStr>

Performs the conversion.

impl From<String> for Drc<str>

fn from(string: String) -> Drc<str>

Performs the conversion.

impl From<OsString> for Drc<OsStr>

fn from(os_string: OsString) -> Drc<OsStr>

Performs the conversion.

impl From<PathBuf> for Drc<Path>

fn from(path: PathBuf) -> Drc<Path>

Performs the conversion.

impl<'a> From<&'a CStr> for Drc<CStr>

fn from(c_string: &'a CStr) -> Drc<CStr>

Performs the conversion.

impl<'a> From<&'a str> for Drc<str>

fn from(string: &'a str) -> Drc<str>

Performs the conversion.

impl<'a> From<&'a OsStr> for Drc<OsStr>

fn from(os_string: &'a OsStr) -> Drc<OsStr>

Performs the conversion.

impl<'a> From<&'a Path> for Drc<Path>

fn from(path: &'a Path) -> Drc<Path>

Performs the conversion.

impl<'a, T> From<&'a [T]> for Drc<[T]> where     T: Clone,

fn from(slice: &'a [T]) -> Drc<[T]>

Performs the conversion.

impl<T> From<Arc<T>> for Drc<T> where     T: ?Sized,

fn from(arc: Arc<T>) -> Drc<T>

Performs the conversion.

impl<T> From<Box<T>> for Drc<T> where     T: ?Sized,

fn from(box_: Box<T>) -> Drc<T>

Performs the conversion.

impl<T> From<T> for Drc<T>

fn from(value: T) -> Drc<T>

Performs the conversion.

impl<T> From<Vec<T>> for Drc<[T]>

fn from(vec: Vec<T>) -> Drc<[T]>

Performs the conversion.

impl<T: ?Sized> Hash for Drc<T> where     T: Hash,

fn hash<H>(&self, state: &mut H) where     H: Hasher,

Feeds this value into the given [Hasher].

fn hash_slice<H>(data: &[Self], state: &mut H) where     H: Hasher,

Feeds a slice of this type into the given [Hasher].

impl<T: ?Sized> Ord for Drc<T> where     T: Ord,

fn cmp(&self, other: &Drc<T>) -> Ordering

Comparison for two Drcs.

The two are compared by calling cmp() on their inner values.

Examples

use std::cmp::Ordering;

use drc::Drc;

let five = Drc::new(5);

assert_eq!(Ordering::Less, five.cmp(&Drc::new(6)));

fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

impl<T: ?Sized> PartialEq<Drc<T>> for Drc<T> where     T: PartialEq<T>,

fn eq(&self, other: &Drc<T>) -> bool

Equality for two Drcs.

Two Drcs are equal if their inner values are equal.

Examples

use drc::Drc;

let five = Drc::new(5);

assert!(five == Drc::new(5));

fn ne(&self, other: &Drc<T>) -> bool

Equality for two Drcs.

Two Drcs are unequal if their inner values are unequal.

Examples

use drc::Drc;

let five = Drc::new(5);

assert!(five != Drc::new(6));

impl<T: ?Sized> PartialOrd<Drc<T>> for Drc<T> where     T: PartialOrd<T>,

fn partial_cmp(&self, other: &Drc<T>) -> Option<Ordering>

Partial comparison for two Drcs.

The two are compared by calling partial_cmp() on their inner values.

Examples

use std::cmp::Ordering;

use drc::Drc;

let five = Drc::new(5);

assert_eq!(Some(Ordering::Less), five.partial_cmp(&Drc::new(6)));

fn lt(&self, other: &Drc<T>) -> bool

Less-than comparison for two Drcs.

The two are compared by calling < on their inner values.

Examples

use drc::Drc;

let five = Drc::new(5);

assert!(five < Drc::new(6));

fn le(&self, other: &Drc<T>) -> bool

'Less than or equal to' comparison for two Drcs.

The two are compared by calling <= on their inner values.

Examples

use drc::Drc;

let five = Drc::new(5);

assert!(five <= Drc::new(6));

fn gt(&self, other: &Drc<T>) -> bool

Greater-than comparison for two Drcs.

The two are compared by calling > on their inner values.

Examples

use drc::Drc;

let five = Drc::new(5);

assert!(five > Drc::new(4));

fn ge(&self, other: &Drc<T>) -> bool

'Greater-than or equal to' comparison for two Drcs.

The two are compared by calling >= on their inner values.

Examples

use drc::Drc;

let five = Drc::new(5);

assert!(five >= Drc::new(4));

impl<T: ?Sized> Debug for Drc<T> where     T: Debug,

fn fmt(&self, f: &mut Formatter) -> FmtResult

Formats the value using the given formatter.

impl<T: ?Sized> Display for Drc<T> where     T: Display,

fn fmt(&self, f: &mut Formatter) -> FmtResult

Formats the value using the given formatter.

impl<T> Pointer for Drc<T> where     T: ?Sized,

fn fmt(&self, f: &mut Formatter) -> FmtResult

Formats the value using the given formatter.

impl<T: ?Sized> UnwindSafe for Drc<T> where     T: RefUnwindSafe,