Struct hybrid_rc::Weak

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

Weak<T> represents a non-owning reference to a value managed by a HybridRc<T, _>. The value is accessed by calling upgrade() or upgrade_local() on Weak.

Weak references are typically used to prevent circular references that would keep the shared value alive indefinitely.

The typical way to obtain a Weak<T> is to call HybridRc::downgrade().

Implementations

impl<T: ?Sized> Weak<T>

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

Returns a raw pointer to the value referenced by this Weak<T>.

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

Example

use hybrid_rc::Rc;

let strong = Rc::new(42i32);
let weak = Rc::downgrade(&strong);
{
	let pointer = weak.as_ptr();
	// As long as strong is not dropped, the pointer stays valid
	assert_eq!(42, unsafe { *pointer });
}
drop(strong);
{
	// Calling weak.as_ptr() is still safe, but dereferencing it would lead
	// to undefined behaviour.
	let pointer = weak.as_ptr();
	// assert_eq!(42, unsafe { &*pointer }); // undefined behaviour
}

pub fn upgrade_local(&self) -> Result<Rc<T>, UpgradeError>

Attempts to upgrade the Weak pointer to an Rc.

Note: Only one thread can have Rcs for a value at any point in time. See upgrade() to upgrade to an Arc.

In no_std environments this will only succeed if no Rc exists on any thread.

Errors

• ValueDropped: the referenced value has already been dropped.
• WrongThread: another thread currently holds Rcs for the value.

Example

use hybrid_rc::{Arc, Rc, Weak, UpgradeError};
let strong = Arc::new(42i32);
let weak = Arc::downgrade(&strong);

{
	let strong2 = weak.upgrade_local()?;
	assert_eq!(Arc::as_ptr(&strong), Rc::as_ptr(&strong2));
}

std::mem::drop(strong);

let error = Weak::upgrade_local(&weak).unwrap_err();
assert_eq!(error, UpgradeError::ValueDropped);

pub fn upgrade(&self) -> Result<Arc<T>, UpgradeError>

Attempts to upgrade the Weak pointer to an Arc.

Also see upgrade_local() to upgrade to an Rc.

Errors

• ValueDropped: the referenced value has already been dropped.

pub fn strong_count(&self) -> usize

Gets a lower bound to the number of strong pointers to the inner value.

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

Please understand that another thread might change the count at any time, including potentially between calling this method and acting on the result.

Examples

use hybrid_rc::{Arc, Rc, Weak};

let reference = Rc::new(42);
let _2nd_ref = Rc::clone(&reference);
let shared_ref = Rc::to_shared(&reference);
let _2nd_shared_ref = Arc::clone(&shared_ref);
let weak = Rc::downgrade(&reference);

// shared_ref only knows the count of shared references and that there is at least one
// local reference, so it will show 3 instead of 4:
assert_eq!(Weak::strong_count(&weak), 3);

pub fn weak_count(&self) -> usize

Gets the number of Weak pointers to this allocation.

Please understand that another thread may change the count at any time, including potentially between calling this method and acting on the result. Also there might by off-by-one errors when other threads concurrently upgrade or downgrade pointers.

Examples

use hybrid_rc::{Rc, Weak};

let reference = Rc::new(42);
let weak = Rc::downgrade(&reference);
let _weak_2 = weak.clone();

assert_eq!(Weak::weak_count(&weak), 2);

impl<T> Weak<T>

pub fn new() -> Weak<T>

Constructs a dummy Weak<T>, without allocating any memory.

Trying to upgrade the result will always result in a ValueDropped error.

Trait Implementations

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

fn clone(&self) -> Self

Creates another Weak reference for the same value.

Example

use hybrid_rc::{Rc, Weak};

let strong = Rc::new(42i32);
let weak = Rc::downgrade(&strong);
let weak2 = Weak::clone(&weak);

assert_eq!(weak.as_ptr(), weak2.as_ptr());

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 dummy Weak<T>, without allocating any memory.

See Weak<T>::new().

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

fn drop(&mut self)

Drops the Weak reference.

Once all HybridRc and Weak references to a shared value are dropped, the shared allocation is fully released.

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

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

Formats the value using the given formatter.

If the # flag is used, the state (weak) is written after the address.

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

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