Struct alloc::sync::Weak

pub struct Weak<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>, without allocating any memory. 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());

pub fn as_raw(&self) -> *const T

🔬 This is a nightly-only experimental API. (weak_into_raw #60728)

Returns a raw pointer to the object T pointed to by this Weak<T>.

It is up to the caller to ensure that the object is still alive when accessing it through the pointer.

The pointer may be null or be dangling in case the object has already been destroyed.

Examples

#![feature(weak_into_raw)]

use std::sync::Arc;
use std::ptr;

let strong = Arc::new("hello".to_owned());
let weak = Arc::downgrade(&strong);
// Both point to the same object
assert!(ptr::eq(&*strong, weak.as_raw()));
// The strong here keeps it alive, so we can still access the object.
assert_eq!("hello", unsafe { &*weak.as_raw() });

drop(strong);
// But not any more. We can do weak.as_raw(), but accessing the pointer would lead to
// undefined behaviour.
// assert_eq!("hello", unsafe { &*weak.as_raw() });

pub fn into_raw(self) -> *const T

🔬 This is a nightly-only experimental API. (weak_into_raw #60728)

Consumes the Weak<T> and turns it into a raw pointer.

This converts the weak pointer into a raw pointer, preserving the original weak count. It can be turned back into the Weak<T> with from_raw.

The same restrictions of accessing the target of the pointer as with as_raw apply.

Examples

#![feature(weak_into_raw)]

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

let strong = Arc::new("hello".to_owned());
let weak = Arc::downgrade(&strong);
let raw = weak.into_raw();

assert_eq!(1, Arc::weak_count(&strong));
assert_eq!("hello", unsafe { &*raw });

drop(unsafe { Weak::from_raw(raw) });
assert_eq!(0, Arc::weak_count(&strong));

pub unsafe fn from_raw(ptr: *const T) -> Self

🔬 This is a nightly-only experimental API. (weak_into_raw #60728)

Converts a raw pointer previously created by into_raw back into Weak<T>.

This can be used to safely get a strong reference (by calling upgrade later) or to deallocate the weak count by dropping the Weak<T>.

It takes ownership of one weak count. In case a null is passed, a dangling Weak is returned.

Safety

The pointer must represent one valid weak count. In other words, it must point to T which is or was managed by an Arc and the weak count of that Arc must not have reached 0. It is allowed for the strong count to be 0.

Examples

#![feature(weak_into_raw)]

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

let strong = Arc::new("hello".to_owned());

let raw_1 = Arc::downgrade(&strong).into_raw();
let raw_2 = Arc::downgrade(&strong).into_raw();

assert_eq!(2, Arc::weak_count(&strong));

assert_eq!("hello", &*unsafe { Weak::from_raw(raw_1) }.upgrade().unwrap());
assert_eq!(1, Arc::weak_count(&strong));

drop(strong);

// Decrement the last weak count.
assert!(unsafe { Weak::from_raw(raw_2) }.upgrade().is_none());

impl<T: ?Sized> Weak<T>

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());

pub fn strong_count(&self) -> usize

🔬 This is a nightly-only experimental API. (weak_counts #57977)

Gets the number of strong (Arc) pointers pointing to this value.

If self was created using Weak::new, this will return 0.

pub fn weak_count(&self) -> Option<usize>

🔬 This is a nightly-only experimental API. (weak_counts #57977)

Gets an approximation of the number of Weak pointers pointing to this value.

If self was created using Weak::new, this will return 0. If not, the returned value is at least 1, since self still points to the value.

Accuracy

Due to implementation details, the returned value can be off by 1 in either direction when other threads are manipulating any Arcs or Weaks pointing to the same value.

pub fn ptr_eq(&self, other: &Self) -> bool

Returns true if the two Weaks point to the same value (not just values that compare as equal), or if both don't point to any value (because they were created with Weak::new()).

Notes

Since this compares pointers it means that Weak::new() will equal each other, even though they don't point to any value.

Examples

use std::sync::Arc;

let first_rc = Arc::new(5);
let first = Arc::downgrade(&first_rc);
let second = Arc::downgrade(&first_rc);

assert!(first.ptr_eq(&second));

let third_rc = Arc::new(5);
let third = Arc::downgrade(&third_rc);

assert!(!first.ptr_eq(&third));

Comparing Weak::new.

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

let first = Weak::new();
let second = Weak::new();
assert!(first.ptr_eq(&second));

let third_rc = Arc::new(());
let third = Arc::downgrade(&third_rc);
assert!(!first.ptr_eq(&third));

Trait Implementations

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

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

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

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: ?Sized + Debug> Debug for Weak<T>

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

Formats the value using the given formatter.

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

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

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

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));

let _ = 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>, without allocating memory. 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());