Struct Weak

pub struct Weak<T: ?Sized> { /* private fields */ }

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

This is an equivalent to [std::sync::Weak], but using portable-atomic for synchronization. See the documentation for [std::sync::Weak] for more details.

Note: Unlike std::sync::Weak, coercing Weak<T> to Weak<U> is not possible, not even if the optional cfg portable_atomic_unstable_coerce_unsized is enabled.

Examples

use portable_atomic_util::Arc;
use std::thread;

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

thread::spawn(move || {
    let five = weak_five.upgrade().unwrap();
    assert_eq!(*five, 5);
});

Implementations

impl<T> Weak<T>

pub const fn new() -> Self

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

Examples

use portable_atomic_util::Weak;

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

impl<T> Weak<T>

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

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 portable_atomic_util::{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> Weak<T>

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 portable_atomic_util::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 portable_atomic_util::{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));

impl<T: ?Sized> Weak<T>

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

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 portable_atomic_util::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: &Self) -> 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 portable_atomic_util::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 portable_atomic_util::{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> Clone for Weak<T>

fn clone(&self) -> Self

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

Examples

use portable_atomic_util::{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: ?Sized> Debug for Weak<T>

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

Formats the value using the given formatter.

impl<T> Default for Weak<T>

fn default() -> Self

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

Examples

use portable_atomic_util::Weak;

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

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

fn drop(&mut self)

Drops the Weak pointer.

Examples

use portable_atomic_util::{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 + Sync + Send> Send for Weak<T>

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