Struct Weak

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

A weak reference-counted reference to a RefBox.

See the module documentation for more information.

Accessing the data behind the Weak

See Weak::try_borrow_mut, Weak::try_borrow_mut_or_else and Weak::try_access_mut.

Note: because all borrows are guarded by a single flag, only one borrow is possible at a time and all borrows are mutable.

Implementations

impl<T: ?Sized> Weak<T>

pub fn try_borrow_mut(&self) -> Result<Borrow<'_, T>, BorrowError>

Tries to borrow the data mutably.

Returns

• Ok(Borrow) if the borrow was successful
• Err(BorrowError::Borrowed) if the data was already borrowed
• Err(BorrowError::Dropped) if the owning RefBox was dropped

pub fn try_borrow_mut_or_else<E>( &self, err_borrowed: impl FnOnce() -> E, err_dropped: impl FnOnce() -> E, ) -> Result<Borrow<'_, T>, E>

Tries to borrow the data mutably and returns a custom error if borrowing fails.

pub fn try_access_mut<R, F: FnOnce(&mut T) -> R>( &self, op: F, ) -> Result<R, BorrowError>

Provides access to the data through a closure.

If the data is already borrowed or the owning RefBox is dropped, the closure is not executed and an error is returned. Otherwise, the closure is executed and the output of the closure is returned.

Returns

• Ok(R) if the access was successful
• Err(BorrowError::Borrowed) if the data was already borrowed
• Err(BorrowError::Dropped) if the owning RefBox was dropped

pub fn try_clone(&self) -> Option<Weak<T>>

Tries to clone the weak reference to the data.

Returns

• Some(Weak) if it was successful.
• None if the number of weak pointers overflowed u32::MAX.

pub fn weak_count(&self) -> u32

Returns the total number of Weak pointers that point to the same instance as this one.

pub fn is_alive(&self) -> bool

Returns true if the owner of the data is alive.

pub fn is_borrowed(&self) -> bool

Returns true if the data is currently mutably borrowed.

pub fn is(&self, owner: &RefBox<T>) -> bool

Returns true if this Weak and the supplied RefBox point to the same instance.

pub unsafe fn get_unchecked(&self) -> &T

Returns an immutable reference to the data without checking if the data is already mutably borrowed or dropped.

Safety

1. Ensure there are no mutable references to T.
2. Ensure T is fully initialized (don’t use this in RefBox::new_cyclic).
3. Ensure the owning RefBox is alive for the entire lifetime of the returned reference.

pub unsafe fn get_mut_unchecked(&mut self) -> &mut T

Returns a mutable reference to the data without checking if the data is already mutably borrowed or dropped.

Safety

1. Ensure there are no other references to T.
2. Ensure T is fully initialized (don’t use this in RefBox::new_cyclic).
3. Ensure the owning RefBox is alive for the entire lifetime of the returned reference.

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

Returns a raw pointer to T.

pub fn into_raw(self) -> *mut RefBoxHeap<T>

Turns the Weak into a raw pointer.

pub unsafe fn from_raw(ptr: *mut RefBoxHeap<T>) -> Self

Creates a Weak from a raw pointer.

Safety

Ensure ptr is a valid pointer to a RefBoxHeap<T>.

pub unsafe fn cast<U>(self) -> Weak<U>

Casts a Weak<T> to a Weak<U>.

Safety

Ensure T can be safely cast to U.

Trait Implementations

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

fn clone(&self) -> Self

Copies the reference and increases the reference counter.

Panics

Panics if the number of Refs overflows u32::MAX.

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

fn drop(&mut self)

Executes the destructor for this type.

impl<T: ?Sized> PartialEq<RefBox<T>> for Weak<T>

fn eq(&self, other: &RefBox<T>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T: ?Sized> PartialEq<Weak<T>> for RefBox<T>

fn eq(&self, other: &Weak<T>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

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

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

Returns true if both Weak pointers point to the same instance.

This compares the pointer addresses, not the actual objects themselves, which makes it very fast.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

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