pub struct Weak<T: ?Sized, A: Allocator = Global> { /* private fields */ }Expand description
Weak is a version of Arc 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<Arc<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 Arc without preventing its inner value from being dropped. It is also used to
prevent circular references between Arc pointers, since mutual owning references
would never allow either Arc to be dropped. For example, a tree could
have strong Arc 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 Arc::downgrade.
Implementations§
Source§impl<T, A: Allocator> Weak<T, A>
impl<T, A: Allocator> Weak<T, A>
Source§impl<T: ?Sized> Weak<T>
impl<T: ?Sized> Weak<T>
1.45.0 · Sourcepub unsafe fn from_raw(ptr: *const T) -> Self
pub unsafe fn from_raw(ptr: *const T) -> Self
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 reference (with the exception of pointers created by new,
as these don’t own anything; the method still works on them).
§Safety
The pointer must have originated from the into_raw and must still own its potential
weak reference, and must point to a block of memory allocated by global allocator.
It is allowed for the strong count to be 0 at the time of calling this. Nevertheless, this
takes ownership of one weak reference currently represented as a raw pointer (the weak
count is not modified by this operation) and therefore it must be paired with a previous
call to 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);
// Decrement the last weak count.
assert!(unsafe { Weak::from_raw(raw_2) }.upgrade().is_none());Source§impl<T: ?Sized, A: Allocator> Weak<T, A>
impl<T: ?Sized, A: Allocator> Weak<T, A>
Sourcepub fn allocator(&self) -> &A
🔬This is a nightly-only experimental API. (allocator_api #32838)
pub fn allocator(&self) -> &A
allocator_api #32838)Returns a reference to the underlying allocator.
1.45.0 · Sourcepub fn as_ptr(&self) -> *const T
pub fn as_ptr(&self) -> *const T
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,
unaligned or even null otherwise.
§Examples
use std::sync::Arc;
use std::ptr;
let strong = Arc::new("hello".to_owned());
let weak = Arc::downgrade(&strong);
// Both point to the same object
assert!(ptr::eq(&*strong, weak.as_ptr()));
// The strong here keeps it alive, so we can still access the object.
assert_eq!("hello", unsafe { &*weak.as_ptr() });
drop(strong);
// But not any more. We can do weak.as_ptr(), but accessing the pointer would lead to
// undefined behavior.
// assert_eq!("hello", unsafe { &*weak.as_ptr() });1.45.0 · Sourcepub fn into_raw(self) -> *const T
pub fn into_raw(self) -> *const T
Consumes the Weak<T> and turns it into a raw pointer.
This converts the weak pointer into a raw pointer, while still preserving the ownership of
one weak reference (the weak count is not modified by this operation). 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_ptr apply.
§Examples
Sourcepub fn into_raw_with_allocator(self) -> (*const T, A)
🔬This is a nightly-only experimental API. (allocator_api #32838)
pub fn into_raw_with_allocator(self) -> (*const T, A)
allocator_api #32838)Consumes the Weak<T>, returning the wrapped pointer and allocator.
This converts the weak pointer into a raw pointer, while still preserving the ownership of
one weak reference (the weak count is not modified by this operation). It can be turned
back into the Weak<T> with from_raw_in.
The same restrictions of accessing the target of the pointer as with
as_ptr apply.
§Examples
#![feature(allocator_api)]
use std::sync::{Arc, Weak};
use std::alloc::System;
let strong = Arc::new_in("hello".to_owned(), System);
let weak = Arc::downgrade(&strong);
let (raw, alloc) = weak.into_raw_with_allocator();
assert_eq!(1, Arc::weak_count(&strong));
assert_eq!("hello", unsafe { &*raw });
drop(unsafe { Weak::from_raw_in(raw, alloc) });
assert_eq!(0, Arc::weak_count(&strong));Sourcepub unsafe fn from_raw_in(ptr: *const T, alloc: A) -> Self
🔬This is a nightly-only experimental API. (allocator_api #32838)
pub unsafe fn from_raw_in(ptr: *const T, alloc: A) -> Self
allocator_api #32838)Converts a raw pointer previously created by into_raw back into Weak<T> in the provided
allocator.
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 reference (with the exception of pointers created by new,
as these don’t own anything; the method still works on them).
§Safety
The pointer must have originated from the into_raw and must still own its potential
weak reference, and must point to a block of memory allocated by alloc.
It is allowed for the strong count to be 0 at the time of calling this. Nevertheless, this
takes ownership of one weak reference currently represented as a raw pointer (the weak
count is not modified by this operation) and therefore it must be paired with a previous
call to 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);
// Decrement the last weak count.
assert!(unsafe { Weak::from_raw(raw_2) }.upgrade().is_none());Source§impl<T: ?Sized, A: Allocator> Weak<T, A>
impl<T: ?Sized, A: Allocator> Weak<T, A>
1.4.0 · Sourcepub fn upgrade(&self) -> Option<Arc<T, A>>where
A: Clone,
pub fn upgrade(&self) -> Option<Arc<T, A>>where
A: Clone,
1.41.0 · Sourcepub fn strong_count(&self) -> usize
pub fn strong_count(&self) -> usize
Gets the number of strong (Arc) pointers pointing to this allocation.
If self was created using Weak::new, this will return 0.
1.41.0 · Sourcepub fn weak_count(&self) -> usize
pub fn weak_count(&self) -> usize
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 Arcs or
Weaks pointing to the same allocation.
1.39.0 · Sourcepub fn ptr_eq(&self, other: &Self) -> bool
pub fn ptr_eq(&self, other: &Self) -> bool
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()). However,
this function ignores the metadata of dyn Trait pointers.
§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::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));Comparing Weak::new.
Trait Implementations§
1.4.0 · Source§impl<T: ?Sized, A: Allocator + Clone> Clone for Weak<T, A>
impl<T: ?Sized, A: Allocator + Clone> Clone for Weak<T, A>
1.4.0 · Source§impl<T: ?Sized, A: Allocator> Drop for Weak<T, A>
impl<T: ?Sized, A: Allocator> Drop for Weak<T, A>
Source§fn drop(&mut self)
fn drop(&mut self)
Drops the Weak pointer.
§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); // Doesn't print anything
drop(foo); // Prints "dropped!"
assert!(other_weak_foo.upgrade().is_none());