#[repr(C)]pub struct SharedPtr<T>where
T: SharedPtrTarget,{ /* private fields */ }
Expand description
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§
Sourcepub fn null() -> SharedPtr<T>
pub fn null() -> SharedPtr<T>
Makes a new SharedPtr that is both empty and null.
Matches the behavior of default-constructing a std::shared_ptr.
Sourcepub fn new(value: T) -> SharedPtr<T>where
T: ExternType<Kind = Trivial>,
pub fn new(value: T) -> SharedPtr<T>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.
Sourcepub unsafe fn from_raw(raw: *mut T) -> SharedPtr<T>
pub unsafe fn from_raw(raw: *mut T) -> SharedPtr<T>
Creates 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_delete
on 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 T
is an incomplete type (including void
) or is not
destructible.
§Safety
Pointer must either be null or point to a valid instance of T
heap-allocated in C++ by new
.
Sourcepub fn is_null(&self) -> bool
pub fn is_null(&self) -> bool
Checks 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.
Sourcepub fn as_ref(&self) -> Option<&T>
pub 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.
Sourcepub unsafe fn pin_mut_unchecked(&mut self) -> Pin<&mut T>
pub 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 representation
extern "C++" { type T = ...; }
.
Sourcepub fn as_ptr(&self) -> *const T
pub fn as_ptr(&self) -> *const T
Returns the SharedPtr’s stored pointer as a raw const pointer.
Sourcepub fn as_mut_ptr(&self) -> *mut T
pub fn as_mut_ptr(&self) -> *mut T
Returns 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.
Sourcepub fn downgrade(&self) -> WeakPtr<T>where
T: WeakPtrTarget,
pub fn downgrade(&self) -> WeakPtr<T>where
T: WeakPtrTarget,
Constructs new WeakPtr as a non-owning reference to the object managed
by self
. If self
manages 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§
1.21.0 · Source§fn max(self, other: Self) -> Selfwhere
Self: Sized,
fn max(self, other: Self) -> Selfwhere
Self: Sized,
Auto Trait Implementations§
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
Source§impl<Q, K> Comparable<K> for Q
impl<Q, K> Comparable<K> for Q
Source§impl<Q, K> Equivalent<K> for Q
impl<Q, K> Equivalent<K> for Q
Source§impl<Q, K> Equivalent<K> for Q
impl<Q, K> Equivalent<K> for Q
Source§fn equivalent(&self, key: &K) -> bool
fn equivalent(&self, key: &K) -> bool
key
and return true
if they are equal.Source§impl<T> Instrument for T
impl<T> Instrument for T
Source§fn instrument(self, span: Span) -> Instrumented<Self> ⓘ
fn instrument(self, span: Span) -> Instrumented<Self> ⓘ
Source§fn in_current_span(self) -> Instrumented<Self> ⓘ
fn in_current_span(self) -> Instrumented<Self> ⓘ
Source§impl<T> IntoEither for T
impl<T> IntoEither for T
Source§fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
self
into a Left
variant of Either<Self, Self>
if into_left
is true
.
Converts self
into a Right
variant of Either<Self, Self>
otherwise. Read moreSource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
self
into a Left
variant of Either<Self, Self>
if into_left(&self)
returns true
.
Converts self
into a Right
variant of Either<Self, Self>
otherwise. Read moreSource§impl<T> Pointable for T
impl<T> Pointable for T
Source§impl<T> PolicyExt for Twhere
T: ?Sized,
impl<T> PolicyExt for Twhere
T: ?Sized,
Source§impl<T> QuickToOwned for Twhere
T: ToOwned,
impl<T> QuickToOwned for Twhere
T: ToOwned,
Source§impl<T> ToStringFallible for Twhere
T: Display,
impl<T> ToStringFallible for Twhere
T: Display,
Source§fn try_to_string(&self) -> Result<String, TryReserveError>
fn try_to_string(&self) -> Result<String, TryReserveError>
ToString::to_string
, but without panic on OOM.