Struct Weak

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

Available on crate feature dep_portable_atomic_util only.

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() -> Weak<T>

Available on crate feature alloc only.

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) -> Weak<T>

Available on crate feature alloc only.

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

Available on crate feature alloc only.

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

Available on crate feature alloc only.

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

where T: ?Sized,

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

Available on crate feature alloc only.

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

Available on crate feature alloc only.

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

Available on crate feature alloc only.

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

Available on crate feature alloc only.

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

where T: ?Sized,

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

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

where 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 portable_atomic_util::Weak;

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

impl<T> Drop for Weak<T>

where T: ?Sized,

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> Send for Weak<T>

where T: Sync + Send + ?Sized,

impl<T> Sync for Weak<T>

where T: Sync + Send + ?Sized,