Struct corundum::sync::Weak [−][src]
Expand description
Weak
is a version of Parc
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
<
Parc
<T>>
.
Since a Weak
reference does not count towards ownership, it will not
prevent the value stored in the allocation from being dropped, and Weak
itself makes no guarantees about the value still being present. Thus it may
return None
when upgrade
d. Note however that a Weak
reference
does prevent the allocation itself (the backing store) from being
deallocated.
A Weak
pointer is useful for keeping a temporary reference to the
allocation managed by Parc
without preventing its inner value from being
dropped. It is also used to prevent circular references between Parc
pointers, since mutual owning references would never allow either Parc
to be dropped. For example, a tree could have strong Parc
pointers from
parent nodes to children, and Weak
pointers from children back to their
parents.
The typical way to obtain a Weak
pointer is to call Parc::downgrade
.
Implementations
Attempts to upgrade the Weak
pointer to an Parc
, delaying
dropping of the inner value if successful.
Returns None
if the inner value has since been dropped.
Examples
use corundum::alloc::heap::*; use corundum::sync::Parc; Heap::transaction(|j| { let five = Parc::new(5, j); let weak_five = Parc::downgrade(&five, j); let strong_five = weak_five.upgrade(j); assert!(strong_five.is_some()); // Destroy all strong pointers. drop(strong_five); drop(five); assert!(weak_five.upgrade(j).is_none()); }).unwrap()
Gets the number of strong (Parc
) pointers pointing to this allocation.
If self
was created using Weak::new
, this will return 0.
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 Parc
s or
Weak
s pointing to the same allocation.
Returns true
if the two Weak
s point to the same allocation (similar to
std::ptr::eq
), or if both don’t point to any allocation
(because they were created with Weak::new()
).
Notes
Since this compares pointers it means that Weak::new()
will equal each
other, even though they don’t point to any allocation.