Struct SharedPtr
#[repr(C)]
pub struct SharedPtr<T>
where
T: SharedPtrTarget, { /* private fields */ }Binding to C++ std::shared_ptr<T>.
WARNING: Unlike Rust's Arc<T>, a C++ shared pointer manipulates
pointers to 2 separate objects in general.
-
One is the managed pointer, and its identity is associated with shared ownership of a strong and weak count shared by other SharedPtr and WeakPtr instances having the same managed pointer.
-
The other is the stored pointer, which is commonly either the same as the managed pointer, or is a pointer into some member of the managed object, but can be any unrelated pointer in general.
The managed pointer is the one passed to a deleter upon the strong count
reaching zero, but the stored pointer is the one accessed by deref
operations and methods such as is_null.
A shared pointer is considered empty if the strong count is zero, meaning the managed pointer has been deleted or is about to be deleted. A shared pointer is considered null if the stored pointer is the null pointer. All combinations are possible. To be explicit, a shared pointer can be nonempty and nonnull, or nonempty and null, or empty and nonnull, or empty and null. In general all of these cases need to be considered when handling a SharedPtr.
Implementations
impl<T> SharedPtr<T>
where
T: SharedPtrTarget,
fn null() -> SelfMakes a new SharedPtr that is both empty and null.
Matches the behavior of default-constructing a std::shared_ptr.
fn new(value: T) -> Self where T: ExternType<Kind = Trivial>,Allocates memory on the heap and makes a SharedPtr owner for it.
The shared pointer will be nonempty and nonnull.
unsafe fn from_raw(raw: *mut T) -> SelfCreates a shared pointer from a C++ heap-allocated pointer.
Matches the behavior of std::shared_ptr's constructor
explicit shared_ptr(T*).The SharedPtr gains ownership of the pointer and will call
std::default_deleteon it when the refcount goes to zero.The object pointed to by the input pointer is not relocated by this operation, so any pointers into this data structure elsewhere in the program continue to be valid.
The resulting shared pointer is nonempty regardless of whether the input pointer is null, but may be either null or nonnull.
Panics
Panics if
Tis an incomplete type (includingvoid) or is not destructible.Safety
Pointer must either be null or point to a valid instance of T heap-allocated in C++ by
new.fn is_null(&self) -> boolChecks whether the SharedPtr holds a null stored pointer.
This is the opposite of std::shared_ptr<T>::operator bool.
This method is unrelated to the state of the reference count. It is possible to have a SharedPtr that is nonnull but empty (has a refcount of 0), typically from having been constructed using the alias constructors in C++. Inversely, it is also possible to be null and nonempty.
fn as_ref(&self) -> Option<&T>Returns a reference to the object pointed to by the stored pointer if nonnull, otherwise None.
The shared pointer's managed object may or may not already have been destroyed.
unsafe fn pin_mut_unchecked(&mut self) -> Pin<&mut T>Returns a mutable pinned reference to the object pointed to by the stored pointer.
The shared pointer's managed object may or may not already have been destroyed.
Panics
Panics if the SharedPtr holds a null stored pointer.
Safety
This method makes no attempt to ascertain the state of the reference count. In particular, unlike
Arc::get_mut, we do not enforce absence of other SharedPtr and WeakPtr referring to the same data as this one. As always, it is Undefined Behavior to have simultaneous references to the same value while a Rust exclusive reference to it exists anywhere in the program.For the special case of CXX opaque C++ types, this method can be used to safely call thread-safe non-const member functions on a C++ object without regard for whether the reference is exclusive. This capability applies only to opaque types
extern "C++" { type T; }. It does not apply to extern types defined with a non-opaque Rust representationextern "C++" { type T = ...; }.fn as_ptr(&self) -> *const TReturns the SharedPtr's stored pointer as a raw const pointer.
fn as_mut_ptr(&self) -> *mut TReturns the SharedPtr's stored pointer as a raw mutable pointer.
As with std::shared_ptr<T>::get, this doesn't require that you hold an exclusive reference to the SharedPtr. This differs from Rust norms, so extra care should be taken in the way the pointer is used.
fn downgrade(&self) -> WeakPtr<T> where T: WeakPtrTarget,Constructs new WeakPtr as a non-owning reference to the object managed by
self. Ifselfmanages no object, the WeakPtr manages no object too.Matches the behavior of std::weak_ptr<T>::weak_ptr(const std::shared_ptr<T> &).
Trait Implementations
impl<T> Clone for SharedPtr<T>
where
T: SharedPtrTarget,
fn clone(&self) -> Self
impl<T> Debug for SharedPtr<T>
where
T: Debug + SharedPtrTarget,
fn fmt(&self, formatter: &mut Formatter<'_>) -> Result
impl<T> Deref for SharedPtr<T>
where
T: SharedPtrTarget,
type Target = T;fn deref(&self) -> &Self::Target
impl<T> Display for SharedPtr<T>
where
T: Display + SharedPtrTarget,
fn fmt(&self, formatter: &mut Formatter<'_>) -> Result
impl<T> Drop for SharedPtr<T>
where
T: SharedPtrTarget,
fn drop(&mut self)
impl<T> Eq for SharedPtr<T>
where
T: Eq + SharedPtrTarget,
impl<T> From<UniquePtr<T>> for SharedPtr<T>
where
T: UniquePtrTarget + SharedPtrTarget,
fn from(unique: UniquePtr<T>) -> Self
impl<T> Hash for SharedPtr<T>
where
T: Hash + SharedPtrTarget,
fn hash<H>(&self, hasher: &mut H) where H: Hasher,
impl<T> Ord for SharedPtr<T>
where
T: Ord + SharedPtrTarget,
fn cmp(&self, other: &Self) -> Ordering
impl<T> PartialEq for SharedPtr<T>
where
T: PartialEq + SharedPtrTarget,
fn eq(&self, other: &Self) -> bool
impl<T> PartialOrd for SharedPtr<T>
where
T: PartialOrd + SharedPtrTarget,
fn partial_cmp(&self, other: &Self) -> Option<Ordering>
impl<T> Send for SharedPtr<T>
where
T: Send + Sync + SharedPtrTarget,
impl<T> Sync for SharedPtr<T>
where
T: Send + Sync + SharedPtrTarget,
impl<T> Unpin for SharedPtr<T>
where
T: SharedPtrTarget,
Auto Trait Implementations
impl<T> Freeze for SharedPtr<T>
where
PhantomData<T>: Freeze,
impl<T> RefUnwindSafe for SharedPtr<T>
where
PhantomData<T>: RefUnwindSafe,
impl<T> UnsafeUnpin for SharedPtr<T>
where
PhantomData<T>: UnsafeUnpin,
impl<T> UnwindSafe for SharedPtr<T>
where
PhantomData<T>: UnwindSafe,
Blanket Implementations
impl<P, T> Receiver for SharedPtr<T>
where
P: Deref<Target = T> + ?Sized,
T: ?Sized,
type Target = T;
impl<T> Any for SharedPtr<T>
where
T: 'static + ?Sized,
fn type_id(&self) -> TypeId
impl<T> Borrow<T> for SharedPtr<T>
where
T: ?Sized,
fn borrow(&self) -> &T
impl<T> BorrowMut<T> for SharedPtr<T>
where
T: ?Sized,
fn borrow_mut(&mut self) -> &mut T
impl<T> CloneToUninit for SharedPtr<T>
where
T: Clone,
unsafe fn clone_to_uninit(&self, dest: *mut u8)
impl<T> From<T> for SharedPtr<T>
fn from(t: T) -> TReturns the argument unchanged.
impl<T> ToOwned for SharedPtr<T>
where
T: Clone,
type Owned = T;fn to_owned(&self) -> Tfn clone_into(&self, target: &mut T)
impl<T> ToString for SharedPtr<T>
where
T: Display + ?Sized,
fn to_string(&self) -> String
impl<T, U> Into<U> for SharedPtr<T>
where
U: From<T>,
fn into(self) -> UCalls
U::from(self).That is, this conversion is whatever the implementation of
[From]<T> for Uchooses to do.
impl<T, U> TryFrom<U> for SharedPtr<T>
where
U: Into<T>,
type Error = Infallible;fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
impl<T, U> TryInto<U> for SharedPtr<T>
where
U: TryFrom<T>,
type Error = <U as TryFrom<T>>::Error;fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>