Struct std::sync::Weak

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

Weak is a version of Arc 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<Arc<T>>.

Since a Weak reference does not count towards ownership, it will not prevent the inner value from being dropped, and 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 Arc without extending its lifetime. It is also used to prevent circular references between Arc pointers, since mutual owning references would never allow either Arc to be dropped. For example, a tree could have strong Arc pointers from parent nodes to children, and Weak pointers from children back to their parents.

The typical way to obtain a Weak pointer is to call Arc::downgrade.

Methods

impl<T> Weak<T>

pub fn new() -> Weak<T>

Constructs a new Weak<T>, allocating memory for T without initializing it. Calling upgrade on the return value always gives None.

Examples

use std::sync::Weak;

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

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

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

Attempts to upgrade the Weak pointer to an Arc, extending the lifetime of the value if successful.

Returns None if the value has since been dropped.

Examples

use std::sync::Arc;

let five = Arc::new(5);

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

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

// Destroy all strong pointers.
drop(strong_five);
drop(five);

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

Trait Implementations

impl<T, U> CoerceUnsized<Weak<U>> for Weak<T> where
    T: Unsize<U> + ?Sized,
    U: ?Sized, 

impl<T> Sync for Weak<T> where
    T: Send + Sync + ?Sized, 

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 std::sync::{Arc, Weak};

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

Weak::clone(&weak_five);

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

Performs copy-assignment from source.

impl<T> Default for Weak<T>

fn default() -> Weak<T>

Constructs a new Weak<T>, allocating memory for T without initializing it. Calling upgrade on the return value always gives None.

Examples

use std::sync::Weak;

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

impl<T> Debug for Weak<T> where
    T: Debug + ?Sized, 

fn fmt(&self, f: &mut Formatter) -> Result<(), Error>

Formats the value using the given formatter.

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

fn drop(&mut self)

Drops the Weak pointer.

Examples

use std::sync::{Arc, Weak};

struct Foo;

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

let foo = Arc::new(Foo);
let weak_foo = Arc::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> Send for Weak<T> where
    T: Send + Sync + ?Sized,