1.4.0[−][src]Struct std::rc::Weak
Weak
is a version of Rc
that holds a non-owning reference to the
managed value. The value is accessed by calling upgrade
on the Weak
pointer, which returns an Option
<
Rc
<T>>
.
Since a Weak
reference does not count towards ownership, it will not
prevent the inner value from being dropped, and Weak
itself makes no
guarantees about the value still being present and may return None
when upgrade
d.
A Weak
pointer is useful for keeping a temporary reference to the value
within Rc
without extending its lifetime. It is also used to prevent
circular references between Rc
pointers, since mutual owning references
would never allow either Rc
to be dropped. For example, a tree could
have strong Rc
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 Rc::downgrade
.
Methods
impl<T> Weak<T>
[src]
pub fn new() -> Weak<T>
1.10.0[src]
Constructs a new Weak<T>
, without allocating any memory.
Calling upgrade
on the return value always gives None
.
Examples
use std::rc::Weak; let empty: Weak<i64> = Weak::new(); assert!(empty.upgrade().is_none());Run
pub fn as_raw(&self) -> *const T
[src]
Returns a raw pointer to the object T
pointed to by this Weak<T>
.
It is up to the caller to ensure that the object is still alive when accessing it through the pointer.
The pointer may be null
or be dangling in case the object has already been destroyed.
Examples
#![feature(weak_into_raw)] use std::rc::Rc; use std::ptr; let strong = Rc::new("hello".to_owned()); let weak = Rc::downgrade(&strong); // Both point to the same object assert!(ptr::eq(&*strong, weak.as_raw())); // The strong here keeps it alive, so we can still access the object. assert_eq!("hello", unsafe { &*weak.as_raw() }); drop(strong); // But not any more. We can do weak.as_raw(), but accessing the pointer would lead to // undefined behaviour. // assert_eq!("hello", unsafe { &*weak.as_raw() });Run
pub fn into_raw(self) -> *const T
[src]
Consumes the Weak<T>
and turns it into a raw pointer.
This converts the weak pointer into a raw pointer, preserving the original weak count. 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_raw
apply.
Examples
#![feature(weak_into_raw)] use std::rc::{Rc, Weak}; let strong = Rc::new("hello".to_owned()); let weak = Rc::downgrade(&strong); let raw = weak.into_raw(); assert_eq!(1, Rc::weak_count(&strong)); assert_eq!("hello", unsafe { &*raw }); drop(unsafe { Weak::from_raw(raw) }); assert_eq!(0, Rc::weak_count(&strong));Run
pub unsafe fn from_raw(ptr: *const T) -> Weak<T>
[src]
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 count. In case a null
is passed, a dangling Weak
is
returned.
Safety
The pointer must represent one valid weak count. In other words, it must point to T
which
is or was managed by an Rc
and the weak count of that Rc
must not have reached
0. It is allowed for the strong count to be 0.
Examples
#![feature(weak_into_raw)] use std::rc::{Rc, Weak}; let strong = Rc::new("hello".to_owned()); let raw_1 = Rc::downgrade(&strong).into_raw(); let raw_2 = Rc::downgrade(&strong).into_raw(); assert_eq!(2, Rc::weak_count(&strong)); assert_eq!("hello", &*unsafe { Weak::from_raw(raw_1) }.upgrade().unwrap()); assert_eq!(1, Rc::weak_count(&strong)); drop(strong); // Decrement the last weak count. assert!(unsafe { Weak::from_raw(raw_2) }.upgrade().is_none());Run
impl<T> Weak<T> where
T: ?Sized,
[src]
T: ?Sized,
pub fn upgrade(&self) -> Option<Rc<T>>
[src]
Attempts to upgrade the Weak
pointer to an Rc
, extending
the lifetime of the value if successful.
Returns None
if the value has since been dropped.
Examples
use std::rc::Rc; let five = Rc::new(5); let weak_five = Rc::downgrade(&five); let strong_five: Option<Rc<_>> = weak_five.upgrade(); assert!(strong_five.is_some()); // Destroy all strong pointers. drop(strong_five); drop(five); assert!(weak_five.upgrade().is_none());Run
pub fn strong_count(&self) -> usize
[src]
Gets the number of strong (Rc
) pointers pointing to this value.
If self
was created using Weak::new
, this will return 0.
pub fn weak_count(&self) -> Option<usize>
[src]
Gets the number of Weak
pointers pointing to this value.
If self
was created using Weak::new
, this will return None
. If
not, the returned value is at least 1, since self
still points to the
value.
pub fn ptr_eq(&self, other: &Weak<T>) -> bool
1.39.0[src]
Returns true
if the two Weak
s point to the same value (not just
values that compare as equal), or if both don't point to any value
(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 value.
Examples
use std::rc::Rc; let first_rc = Rc::new(5); let first = Rc::downgrade(&first_rc); let second = Rc::downgrade(&first_rc); assert!(first.ptr_eq(&second)); let third_rc = Rc::new(5); let third = Rc::downgrade(&third_rc); assert!(!first.ptr_eq(&third));Run
Comparing Weak::new
.
use std::rc::{Rc, Weak}; let first = Weak::new(); let second = Weak::new(); assert!(first.ptr_eq(&second)); let third_rc = Rc::new(()); let third = Rc::downgrade(&third_rc); assert!(!first.ptr_eq(&third));Run
Trait Implementations
impl<T, U> CoerceUnsized<Weak<U>> for Weak<T> where
T: Unsize<U> + ?Sized,
U: ?Sized,
[src]
T: Unsize<U> + ?Sized,
U: ?Sized,
impl<T> !Sync for Weak<T> where
T: ?Sized,
[src]
T: ?Sized,
impl<T> Clone for Weak<T> where
T: ?Sized,
[src]
T: ?Sized,
fn clone(&self) -> Weak<T>
[src]
Makes a clone of the Weak
pointer that points to the same value.
Examples
use std::rc::{Rc, Weak}; let weak_five = Rc::downgrade(&Rc::new(5)); let _ = Weak::clone(&weak_five);Run
fn clone_from(&mut self, source: &Self)
1.0.0[src]
impl<T> Drop for Weak<T> where
T: ?Sized,
[src]
T: ?Sized,
fn drop(&mut self)
[src]
Drops the Weak
pointer.
Examples
use std::rc::{Rc, Weak}; struct Foo; impl Drop for Foo { fn drop(&mut self) { println!("dropped!"); } } let foo = Rc::new(Foo); let weak_foo = Rc::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());Run
impl<T> !Send for Weak<T> where
T: ?Sized,
[src]
T: ?Sized,
impl<T> Debug for Weak<T> where
T: Debug + ?Sized,
[src]
T: Debug + ?Sized,
impl<T, U> DispatchFromDyn<Weak<U>> for Weak<T> where
T: Unsize<U> + ?Sized,
U: ?Sized,
[src]
T: Unsize<U> + ?Sized,
U: ?Sized,
impl<T> Default for Weak<T>
1.10.0[src]
Auto Trait Implementations
Blanket Implementations
impl<T> From<T> for T
[src]
impl<T, U> TryFrom<U> for T where
U: Into<T>,
[src]
U: Into<T>,
type Error = Infallible
The type returned in the event of a conversion error.
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
[src]
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,
type Error = <U as TryFrom<T>>::Error
The type returned in the event of a conversion error.
fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>
[src]
impl<T> Borrow<T> for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
T: ?Sized,
ⓘImportant traits for &'_ mut Ffn borrow_mut(&mut self) -> &mut T
[src]
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,
impl<T> ToOwned for T where
T: Clone,
[src]
T: Clone,