Type Alias Weak

pub(crate) type Weak<T> = Weak<T>;

Aliased Type

struct Weak<T> { /* private fields */ }

Implementations

impl<T> Weak<T>

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

impl<T> Weak<T>

where T: ?Sized,

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

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 reference (with the exception of pointers created by new, as these don’t own anything; the method still works on them).

Safety

The pointer must have originated from the into_raw and must still own its potential weak reference.

It is allowed for the strong count to be 0 at the time of calling this. Nevertheless, this takes ownership of one weak reference currently represented as a raw pointer (the weak count is not modified by this operation) and therefore it must be paired with a previous call to into_raw.

Examples

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, A> Weak<T, A>

where A: Allocator,

pub fn new_in(alloc: A) -> Weak<T, A>

🔬This is a nightly-only experimental API. (allocator_api)

Constructs a new Weak<T, A>, without allocating any memory, technically in the provided allocator. Calling upgrade on the return value always gives None.

Examples

#![feature(allocator_api)]

use std::sync::Weak;
use std::alloc::System;

let empty: Weak<i64, _> = Weak::new_in(System);
assert!(empty.upgrade().is_none());

impl<T, A> Weak<T, A>

where A: Allocator, T: ?Sized,

pub fn allocator(&self) -> &A

🔬This is a nightly-only experimental API. (allocator_api)

Returns a reference to the underlying allocator.

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

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

The pointer is valid only if there are some strong references. The pointer may be dangling, unaligned or even null otherwise.

Examples

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_ptr()));
// The strong here keeps it alive, so we can still access the object.
assert_eq!("hello", unsafe { &*weak.as_ptr() });

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

pub fn into_raw(self) -> *const T

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

This converts the weak pointer into a raw pointer, while still preserving the ownership of one weak reference (the weak count is not modified by this operation). 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_ptr apply.

Examples

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 fn into_raw_with_allocator(self) -> (*const T, A)

🔬This is a nightly-only experimental API. (allocator_api)

Consumes the Weak<T>, returning the wrapped pointer and allocator.

This converts the weak pointer into a raw pointer, while still preserving the ownership of one weak reference (the weak count is not modified by this operation). It can be turned back into the Weak<T> with from_raw_in.

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

Examples

#![feature(allocator_api)]
use std::sync::{Arc, Weak};
use std::alloc::System;

let strong = Arc::new_in("hello".to_owned(), System);
let weak = Arc::downgrade(&strong);
let (raw, alloc) = weak.into_raw_with_allocator();

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

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

pub unsafe fn from_raw_in(ptr: *const T, alloc: A) -> Weak<T, A>

🔬This is a nightly-only experimental API. (allocator_api)

Converts a raw pointer previously created by into_raw back into Weak<T> in the provided allocator.

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 reference (with the exception of pointers created by new, as these don’t own anything; the method still works on them).

Safety

The pointer must have originated from the into_raw and must still own its potential weak reference, and must point to a block of memory allocated by alloc.

It is allowed for the strong count to be 0 at the time of calling this. Nevertheless, this takes ownership of one weak reference currently represented as a raw pointer (the weak count is not modified by this operation) and therefore it must be paired with a previous call to into_raw.

Examples

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, A> Weak<T, A>

where A: Allocator, T: ?Sized,

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

where A: Clone,

Attempts to upgrade the Weak pointer to an Arc, delaying dropping of the inner value if successful.

Returns None if the inner 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

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

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

pub fn weak_count(&self) -> usize

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

If self was created using Weak::new, or if there are no remaining strong pointers, this will return 0.

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 allocation.

pub fn ptr_eq(&self, other: &Weak<T, A>) -> bool

Returns true if the two Weaks point to the same allocation similar to ptr::eq, or if both don’t point to any allocation (because they were created with Weak::new()). However, this function ignores the metadata of dyn Trait pointers.

Notes

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

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, A> Clone for Weak<T, A>

where A: Allocator + Clone, T: ?Sized,

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

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

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, A> Debug for Weak<T, A>

where A: Allocator, T: ?Sized,

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

Formats the value using the given formatter.

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

impl<T, A> Drop for Weak<T, A>

where A: Allocator, 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, U, A> CoerceUnsized<Weak<U, A>> for Weak<T, A>

where T: Unsize<U> + ?Sized, A: Allocator, U: ?Sized,

impl<T, U> DispatchFromDyn<Weak<U>> for Weak<T>

where T: Unsize<U> + ?Sized, U: ?Sized,

impl<T, A> PinCoerceUnsized for Weak<T, A>

where A: Allocator, T: ?Sized,

impl<T, A> Send for Weak<T, A>

where T: Sync + Send + ?Sized, A: Allocator + Send,

impl<T, A> Sync for Weak<T, A>

where T: Sync + Send + ?Sized, A: Allocator + Sync,