Struct drc::Weak

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

Weak is a version of Drc that holds a non-owning reference to the managed value. The value is accessed by calling upgrade on the Weak pointer, which returns an Option < Drc<T> >.

Since a Weak reference does not count towards ownership, it will not prevent the inner value from being dropped, and the Weak itself makes no guarantees about the value still being present and may return None when upgraded.

A Weak pointer is useful for keeping a temporary reference to the value within Drc without extending its lifetime. It is also used to prevent circular references between Drc pointers, since mutual owning references would never allow either Drc to be dropped. However, this use is generally not recommended for Drcs because "interior" Drcs would be inaccessible and remove Send and Sync from the type, meaning an Rc would be just as good for the task.

Something that might work better is using Arcs and weak Arcs within the structure, with the outermost reference obviously having the potential to be converted into a Drc or Weak Drc (i.e. this Weak).

The typical way to obtain a Weak pointer is to call Drc::downgrade. Using Weak::with_weak_arc is not recommended for most cases, as this performs unnecessary allocation without even knowing if the pointed-to value is still there!

Methods

impl<T> Weak<T>

pub fn new() -> Weak<T>

Constructs a new Weak<T>, allocating memory for not only T and its atomic reference counts but also the local reference counts. Calling upgrade on the return value always gives None.

Exercise restrain when using this method; if possible it is recommended to simply use the weak Arc's new method for whatever purpose this new method would fulfill.

Examples

use drc::Weak;

let empty: Weak<i64> = Weak::new();
assert!(empty.upgrade().is_none());

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

pub fn with_weak_arc(weak_arc: WeakArc<T>) -> Weak<T>

Constructs a new Weak pointer, allocating memory for local reference counts, but using a pre-constructed weak Arc. Calling upgrade on the return value may or may not return a Drc. If the Drc can be created, it will make use of this allocated memory.

Exercise restrain when using this method; if possible it is recommended to simply use the weak Arc for whatever purpose this Weak would fulfill.

This method was chosen over an implementation of the from method for a reverse detachment to make it clear that care should be taken when using this operation instead of alternatives.

Examples

use std::sync::Arc;

use drc::{Drc, Weak};

let five = Arc::new(5);

let weak_five = Weak::with_weak_arc(Arc::downgrade(&five));

let strong_five: Option<Drc<_>> = weak_five.upgrade();
assert!(strong_five.is_some());

// This is not a recommended use of `with_weak_arc`, as the same could be
// done with `Arc`'s `Weak` type.

pub fn upgrade(&self) -> Option<Drc<T>>

Attempts to upgrade the Weak pointer to a Drc, extending the lifetime of the value if successful.

Returns None if the value has since been dropped.

Note that even if there are no Drc strong pointers associated with the same Arc, the value may still persist. Since this Weak associates with a weak Arc, meaning that a Drc may still be returned even if the local strong pointer count is 0 (because a new Arc can be generated by upgrading the internal weak Arc).

Examples

use drc::Drc;

let five = Drc::new(5);

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

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

let strong_five: Option<Drc<_>> = weak_five.upgrade();
assert!(strong_five.is_some());

drop(strong_five);
drop(five);

let strong_five: Option<Drc<_>> = weak_five.upgrade();
assert!(strong_five.is_some());

drop(strong_five);
drop(detached_five);

assert!(weak_five.upgrade().is_none());

pub fn detach(&self) -> WeakArc<T>

Clone the internal weak Arc (incrementing the atomic weak reference count) so that the shared state can be weakly referenced on another thread. Then, return this newly cloned weak Arc. To convert the weak Arc back into this type of Weak (usually not recommended), use Weak::with_weak_arc.

Examples

use std::sync::Weak as WeakArc;

use drc::Drc;

let five = Drc::new(5);

let weak_five = Drc::downgrade(&five);
let detached_weak_five: WeakArc<_> = weak_five.detach();

assert!(Drc::arc_ptr_eq(
    &weak_five.upgrade().unwrap(),
    &detached_weak_five.upgrade().unwrap()
));

Trait Implementations

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

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

Makes a clone of the Weak pointer that points to the same value.

Examples

use drc::{Drc, Weak};

let weak_five = Drc::downgrade(&Drc::new(5));

Weak::clone(&weak_five);

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

Performs copy-assignment from source.

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

fn drop(&mut self)

Drops the Weak pointer.

Examples

use drc::{Drc, Weak};

struct Foo;

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

let foo = Drc::new(Foo);
let weak_foo = Drc::downgrade(&foo);
let other_weak_foo = Weak::clone(&weak_foo);

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

assert!(other_weak_foo.upgrade().is_none());

impl<T> Default for Weak<T>

fn default() -> Weak<T>

Constructs a new Weak<T>, allocating memory for not only T and its atomic reference counts but also the local reference counts. Calling upgrade on the return value always gives None.

Exercise restrain when using this method; if possible it is recommended to simply use the weak Arc's Default implementation for whatever purpose this new method would fulfill.

Examples

use drc::Weak;

let empty: Weak<i64> = Default::default();
assert!(empty.upgrade().is_none());

impl<T> Debug for Weak<T>

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

Formats the value using the given formatter.