pub struct QPtr<T: StaticUpcast<QObject>> { /* private fields */ }
Expand description
A smart pointer that automatically sets to null when the object is deleted.
QPtr
exposes functionality provided by the QPointer<T>
C++ class.
QPtr
can only contain a pointer to a QObject
-based object. When that object is
deleted, QPtr
automatically becomes a null pointer.
Note that dereferencing a null QPtr
will panic, so if it’s known that the object may
already have been deleted, you should use is_null()
, as_ref()
,
or a similar method to check
if the object is still alive before calling its methods.
QPtr
is not an owning pointer, similar to cpp_core::Ptr
. If you actually own the object,
you should convert it to QBox
(it will delete the object when dropped if it has no parent)
or CppBox
(it will always delete the object when dropped). QPtr
provides into_qbox
and
to_box
helpers for that.
Safety
While QPtr
is much safer than cpp_core::Ptr
and prevents use-after-free in common cases,
it is unsafe to use in Rust terms. QPtr::new
must receive a valid pointer or a null pointer,
otherwise the behavior is undefined. You should not store pointers of other types
(e.g. Ptr
, Ref
, or raw pointers) produced by QPtr
because, unlike QPtr
, these
pointers will not become null pointers when the object is deleted.
It’s still possible to cause use-after-free by calling a method through QPtr
.
Even in a single threaded program, the accessed object can be deleted by a nested call
while one of its methods is still running. In multithreaded context, the object can be deleted
in another thread between the null check and the method call, also resulting in undefined
behavior.
Implementations§
source§impl<T: StaticUpcast<QObject>> QPtr<T>
impl<T: StaticUpcast<QObject>> QPtr<T>
sourcepub unsafe fn new(target: impl CastInto<Ptr<T>>) -> Self
pub unsafe fn new(target: impl CastInto<Ptr<T>>) -> Self
Creates a QPtr
from a Ptr
.
Safety
target
must be either a valid pointer to an object or a null pointer.
See type level documentation.
sourcepub unsafe fn from_raw(target: *const T) -> Self
pub unsafe fn from_raw(target: *const T) -> Self
Creates a QPtr
from a raw pointer.
Safety
target
must be either a valid pointer to an object or a null pointer.
See type level documentation.
sourcepub unsafe fn null() -> Self
pub unsafe fn null() -> Self
Creates a null pointer.
Note that you can also use NullPtr
to specify a null pointer to a function accepting
impl CastInto<Ptr<_>>
. Unlike Ptr
, NullPtr
is not a generic type, so it will
not cause type inference issues.
Note that accessing the content of a null QPtr
through Deref
will result
in a panic.
Safety
Null pointers must not be dereferenced. See type level documentation.
sourcepub unsafe fn as_raw_ptr(&self) -> *const T
pub unsafe fn as_raw_ptr(&self) -> *const T
sourcepub unsafe fn as_mut_raw_ptr(&self) -> *mut T
pub unsafe fn as_mut_raw_ptr(&self) -> *mut T
sourcepub unsafe fn as_ref(&self) -> Option<Ref<T>>
pub unsafe fn as_ref(&self) -> Option<Ref<T>>
Returns the content as a const Ref
. Returns None
if self
is a null pointer.
Safety
See type level documentation.
sourcepub unsafe fn as_raw_ref<'a>(&self) -> Option<&'a T>
pub unsafe fn as_raw_ref<'a>(&self) -> Option<&'a T>
Returns a reference to the value. Returns None
if the pointer is null.
Safety
self
must be valid.
The content must not be read or modified through other ways while the returned reference
exists.See type level documentation.
sourcepub unsafe fn as_mut_raw_ref<'a>(&self) -> Option<&'a mut T>
pub unsafe fn as_mut_raw_ref<'a>(&self) -> Option<&'a mut T>
Returns a mutable reference to the value. Returns None
if the pointer is null.
Safety
self
must be valid.
The content must not be read or modified through other ways while the returned reference
exists.See type level documentation.
sourcepub unsafe fn static_upcast<U>(&self) -> QPtr<U>
pub unsafe fn static_upcast<U>(&self) -> QPtr<U>
Converts the pointer to the base class type U
.
Safety
This operation is safe as long as self
is valid or null. See type level documentation.
sourcepub unsafe fn static_downcast<U>(&self) -> QPtr<U>
pub unsafe fn static_downcast<U>(&self) -> QPtr<U>
Converts the pointer to the derived class type U
.
It’s recommended to use dynamic_cast
instead because it performs a checked conversion.
Safety
This operation is safe as long as self
is valid and it’s type is U
or inherits from U
,
of if self
is a null pointer. See type level documentation.
sourcepub unsafe fn dynamic_cast<U>(&self) -> QPtr<U>
pub unsafe fn dynamic_cast<U>(&self) -> QPtr<U>
Converts the pointer to the derived class type U
. Returns None
if the object’s type
is not U
and doesn’t inherit U
.
Safety
This operation is safe as long as self
is valid or null. See type level documentation.
sourcepub unsafe fn to_box(&self) -> Option<CppBox<T>>where
T: CppDeletable,
pub unsafe fn to_box(&self) -> Option<CppBox<T>>where
T: CppDeletable,
Converts this pointer to a CppBox
. Returns None
if self
is a null pointer.
Use this function to take ownership of the object. This is
the same as CppBox::new
. CppBox
will delete the object when dropped.
You can also use into_qbox
to convert the pointer to a QBox
.
Unlike CppBox
, QBox
will only delete the object if it has no parent.
Safety
CppBox
will attempt to delete the object on drop. If something else also tries to
delete this object before or after that, the behavior is undefined.
See type level documentation.
sourcepub unsafe fn into_q_box(self) -> QBox<T>where
T: CppDeletable,
pub unsafe fn into_q_box(self) -> QBox<T>where
T: CppDeletable,
Converts this pointer to a QBox
.
Use this function to take ownership of the object. This is
the same as QBox::from_q_mut_ptr
.
Safety
See type level documentation.
Trait Implementations§
source§impl<'a, T> AsReceiver for &'a QPtr<T>
impl<'a, T> AsReceiver for &'a QPtr<T>
§type Arguments = <T as AsReceiver>::Arguments
type Arguments = <T as AsReceiver>::Arguments
source§fn as_receiver(&self) -> Receiver<Self::Arguments>
fn as_receiver(&self) -> Receiver<Self::Arguments>
source§impl<T: StaticUpcast<QObject>> Deref for QPtr<T>
impl<T: StaticUpcast<QObject>> Deref for QPtr<T>
Allows to call member functions of T
and its base classes directly on the pointer.
Panics if the pointer is null.