Struct std::sync::Weak

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

Weak 是 Arc 的版本，该版本对托管分配具有非所有权引用。 通过调用 Weak 指针上的 upgrade 来访问该分配，该指针返回 Option<Arc<T>>。

由于 Weak 引用不计入所有权，因此它不会防止存储在分配中的值被丢弃，并且 Weak 本身不保证该值仍然存在。

因此，当 upgrade 时，它可能返回 None。 但是请注意，Weak 引用 确实 会阻止分配本身 (后备存储) 被释放。

Weak 指针可用于保持对 Arc 管理的分配的临时引用，而又不会阻止其内部值被丢弃。 它也用于防止 Arc 指针之间的循环引用，因为相互拥有引用将永远不允许丢弃 Arc。 例如，一棵树可以具有从父节点到子节点的强 Arc 指针，以及从子节点到其父节点的 Weak 指针。

获取 Weak 指针的典型方法是调用 Arc::downgrade。

Implementations

impl<T> Weak<T>

pub fn new() -> Weak<T>

创建一个新的 Weak<T>，而不分配任何内存。 在返回值上调用 upgrade 总是得到 None。

Examples

use std::sync::Weak;

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

impl<T> Weak<T> where
    T: ?Sized, 

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

返回对此 Weak<T> 指向的对象 T 的裸指针。

该指针仅在有一些强引用时才有效。 指针可能悬空，未对齐，或者甚至 null。

Examples

use std::sync::Arc;
use std::ptr;

let strong = Arc::new("hello".to_owned());
let weak = Arc::downgrade(&strong);
// 两者都指向同一个对象
assert!(ptr::eq(&*strong, weak.as_ptr()));
// 这里的强项使它保持活动状态，因此我们仍然可以访问该对象。
assert_eq!("hello", unsafe { &*weak.as_ptr() });

drop(strong);
// 但是没有更多了。
// 我们可以执行 weak.as_ptr()，但是访问指针将导致未定义的行为。
// assert_eq!("hello", unsafe { &*weak.as_ptr() });

pub fn into_raw(self) -> *const T

消耗 Weak<T> 并将其转换为裸指针。

这会将弱指针转换为裸指针，同时仍保留一个弱引用的所有权 (此操作不会修改弱引用计数)。 可以将其转换回带有 from_raw 的 Weak<T>。

与 as_ptr 一样，访问指针目标的限制也适用。

Examples

use std::sync::{Arc, Weak};

let strong = Arc::new("hello".to_owned());
let weak = Arc::downgrade(&strong);
let raw = weak.into_raw();

assert_eq!(1, Arc::weak_count(&strong));
assert_eq!("hello", unsafe { &*raw });

drop(unsafe { Weak::from_raw(raw) });
assert_eq!(0, Arc::weak_count(&strong));

pub unsafe fn from_raw(ptr: *const T) -> Weak<T>

将先前由 into_raw 创建的裸指针转换回 Weak<T>。

这可以用于安全地获得强引用 (稍后调用 upgrade) 或通过丢弃 Weak<T> 来分配弱引用计数。

它拥有一个弱引用的所有权 (由 new 创建的指针除外，因为它们不拥有任何东西; 该方法仍适用于它们)。

Safety

指针必须起源于 into_raw，并且仍然必须拥有其潜在的弱引用。

调用时允许强引用计数为 0。 不过，这需要当前表示为裸指针的弱引用的所有权 (该操作不会修改弱引用计数)，因此必须与 into_raw 的先前调用配对。

Examples

use std::sync::{Arc, Weak};

let strong = Arc::new("hello".to_owned());

let raw_1 = Arc::downgrade(&strong).into_raw();
let raw_2 = Arc::downgrade(&strong).into_raw();

assert_eq!(2, Arc::weak_count(&strong));

assert_eq!("hello", &*unsafe { Weak::from_raw(raw_1) }.upgrade().unwrap());
assert_eq!(1, Arc::weak_count(&strong));

drop(strong);

// 减少最后一个弱引用计数。
assert!(unsafe { Weak::from_raw(raw_2) }.upgrade().is_none());

impl<T> Weak<T> where
    T: ?Sized, 

pub fn upgrade(&self) -> Option<Arc<T>>

尝试将 Weak 指针升级到 Arc，如果成功，则延迟内部值的丢弃。

如果内部值已经被丢弃，则返回 None。

Examples

use std::sync::Arc;

let five = Arc::new(5);

let weak_five = Arc::downgrade(&five);

let strong_five: Option<Arc<_>> = weak_five.upgrade();
assert!(strong_five.is_some());

// 销毁所有强指针。
drop(strong_five);
drop(five);

assert!(weak_five.upgrade().is_none());

pub fn strong_count(&self) -> usize

获取指向该分配的强 (Arc) 指针的数量。

如果 self 是使用 Weak::new 创建的，则将返回 0。

pub fn weak_count(&self) -> usize

获取指向该分配的 Weak 指针的数量的近似值。

如果 self 是使用 Weak::new 创建的，或者没有剩余的强指针，则它将返回 0。

Accuracy

由于实现细节，当其他线程操纵指向同一分配的任何 Arc 或 Weak 时，返回的值可以在任一方向上都减 1。

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

如果两个 Weak' 指向相同的分配 (类似于 [ptr::eq])，或者两个都不指向任何分配 (因为它们是用 Weak::new()创建的)，则返回true`。

Notes

由于这将比较指针，这意味着 Weak::new() 将彼此相等，即使它们不指向任何分配。

Examples

use std::sync::Arc;

let first_rc = Arc::new(5);
let first = Arc::downgrade(&first_rc);
let second = Arc::downgrade(&first_rc);

assert!(first.ptr_eq(&second));

let third_rc = Arc::new(5);
let third = Arc::downgrade(&third_rc);

assert!(!first.ptr_eq(&third));

比较 Weak::new。

use std::sync::{Arc, Weak};

let first = Weak::new();
let second = Weak::new();
assert!(first.ptr_eq(&second));

let third_rc = Arc::new(());
let third = Arc::downgrade(&third_rc);
assert!(!first.ptr_eq(&third));

Trait Implementations

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

pub fn clone(&self) -> Weak<T>

克隆 Weak 指针，该指针指向相同的分配。

Examples

use std::sync::{Arc, Weak};

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

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

fn clone_from(&mut self, source: &Self)

从 source 执行复制分配。

impl<T> Debug for Weak<T> where
    T: Debug + ?Sized, 

pub fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

使用给定的格式化程序格式化该值。

impl<T> Default for Weak<T>

pub fn default() -> Weak<T>

创建一个新的 Weak<T>，而不分配内存。 在返回值上调用 upgrade 总是得到 None。

Examples

use std::sync::Weak;

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

impl<T> Drop for Weak<T> where
    T: ?Sized, 

pub fn drop(&mut self)

丢弃 Weak 指针。

Examples

use std::sync::{Arc, Weak};

struct Foo;

impl Drop for Foo {
    fn drop(&mut self) {
        println!("dropped!");
    }
}

let foo = Arc::new(Foo);
let weak_foo = Arc::downgrade(&foo);
let other_weak_foo = Weak::clone(&weak_foo);

drop(weak_foo);   // 不打印任何东西
drop(foo);        // 打印 "dropped!"

assert!(other_weak_foo.upgrade().is_none());

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

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

impl<T> Send for Weak<T> where
    T: Sync + Send + ?Sized, 

impl<T> Sync for Weak<T> where
    T: Sync + Send + ?Sized,