1.4.0[][src]Struct std::rc::Weak

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

Weak is a version of Rc 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<Rc<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 upgraded. 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 Rc without preventing its inner value from being dropped. 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]

🔬 This is a nightly-only experimental API. (weak_into_raw #60728)

Returns a raw pointer to the object T pointed to by this Weak<T>.

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

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]

🔬 This is a nightly-only experimental API. (weak_into_raw #60728)

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]

🔬 This is a nightly-only experimental API. (weak_into_raw #60728)

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 (with the exception of pointers created by new, as these don't have any corresponding weak count).

Safety

The pointer must have originated from the into_raw (or as_raw, provided there was a corresponding forget on the Weak<T>) and must still own its potential weak reference count.

It is allowed for the strong count to be 0 at the time of calling this, but the weak count must be non-zero or the pointer must have originated from a dangling Weak<T> (one created by new).

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]

pub fn upgrade(&self) -> Option<Rc<T>>[src]

Attempts to upgrade the Weak pointer to an Rc, delaying dropping of the inner value if successful.

Returns None if the inner 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]

🔬 This is a nightly-only experimental API. (weak_counts #57977)

Gets the number of strong (Rc) pointers pointing to this allocation.

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

pub fn weak_count(&self) -> Option<usize>[src]

🔬 This is a nightly-only experimental API. (weak_counts #57977)

Gets the number of Weak pointers pointing to this allocation.

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 allocation.

pub fn ptr_eq(&self, other: &Weak<T>) -> bool1.39.0[src]

Returns true if the two Weaks point to the same allocation (similar to 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.

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> Clone for Weak<T> where
    T: ?Sized
[src]

fn clone(&self) -> Weak<T>[src]

Makes a clone of the Weak pointer that points to the same allocation.

Examples

use std::rc::{Rc, Weak};

let weak_five = Rc::downgrade(&Rc::new(5));

let _ = Weak::clone(&weak_five);Run

impl<T, U> CoerceUnsized<Weak<U>> for Weak<T> where
    T: Unsize<U> + ?Sized,
    U: ?Sized
[src]

impl<T> Debug for Weak<T> where
    T: Debug + ?Sized
[src]

impl<T> Default for Weak<T>1.10.0[src]

fn default() -> Weak<T>[src]

Constructs a new Weak<T>, allocating memory for T without initializing it. Calling upgrade on the return value always gives None.

Examples

use std::rc::Weak;

let empty: Weak<i64> = Default::default();
assert!(empty.upgrade().is_none());Run

impl<T, U> DispatchFromDyn<Weak<U>> for Weak<T> where
    T: Unsize<U> + ?Sized,
    U: ?Sized
[src]

impl<T> Drop for Weak<T> where
    T: ?Sized
[src]

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]

impl<T> !Sync for Weak<T> where
    T: ?Sized
[src]

Auto Trait Implementations

impl<T> !RefUnwindSafe for Weak<T>

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

impl<T> !UnwindSafe for Weak<T>

Blanket Implementations

impl<T> Any for T where
    T: 'static + ?Sized
[src]

impl<T> Borrow<T> for T where
    T: ?Sized
[src]

impl<T> BorrowMut<T> for T where
    T: ?Sized
[src]

impl<T> From<T> for T[src]

impl<T, U> Into<U> for T where
    U: From<T>, 
[src]

impl<T> ToOwned for T where
    T: Clone
[src]

type Owned = T

The resulting type after obtaining ownership.

impl<T, U> TryFrom<U> for T where
    U: Into<T>, 
[src]

type Error = !

The type returned in the event of a conversion error.

impl<T, U> TryInto<U> for T where
    U: TryFrom<T>, 
[src]

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.