pub struct Weak<T: ?Sized> { /* private fields */ }
Expand description
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
sourceimpl<T: ?Sized> Weak<T>
impl<T: ?Sized> Weak<T>
sourcepub fn as_ptr(&self) -> *const 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
}
sourcepub fn upgrade_local(&self) -> Result<Rc<T>, UpgradeError>
pub fn upgrade_local(&self) -> Result<Rc<T>, UpgradeError>
Attempts to upgrade the Weak pointer to an Rc
.
Note: Only one thread can have Rc
s 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 holdsRc
s 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);
sourcepub fn upgrade(&self) -> Result<Arc<T>, UpgradeError>
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.
sourcepub fn strong_count(&self) -> usize
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);
sourcepub fn weak_count(&self) -> usize
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);
sourceimpl<T> Weak<T>
impl<T> Weak<T>
sourcepub fn new() -> 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
sourceimpl<T: ?Sized> Clone for Weak<T>
impl<T: ?Sized> Clone for Weak<T>
sourcefn clone(&self) -> Self
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());
1.0.0 · sourcefn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
Performs copy-assignment from source
. Read more
sourceimpl<T> Default for Weak<T>
impl<T> Default for Weak<T>
sourcefn default() -> Self
fn default() -> Self
Constructs a dummy Weak<T>
, without allocating any memory.
See Weak<T>::new()
.
impl<T: ?Sized + Sync + Send> Send for Weak<T>
impl<T: ?Sized + Sync + Send> Sync for Weak<T>
Auto Trait Implementations
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcepub fn borrow_mut(&mut self) -> &mut T
pub fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
sourceimpl<T> ToOwned for T where
T: Clone,
impl<T> ToOwned for T where
T: Clone,
type Owned = T
type Owned = T
The resulting type after obtaining ownership.
sourcepub fn to_owned(&self) -> T
pub fn to_owned(&self) -> T
Creates owned data from borrowed data, usually by cloning. Read more
sourcepub fn clone_into(&self, target: &mut T)
pub fn clone_into(&self, target: &mut T)
toowned_clone_into
)Uses borrowed data to replace owned data, usually by cloning. Read more