omni::core::ObjectPtr¶
Defined in omni/core/IObject.h
-
template<typename
T
>
classomni::core
::
ObjectPtr
¶ Smart pointer wrapper around interface pointers.
This object manages the mundane details of managing the given objects reference count.
There is no implicit raw pointer to ObjectPtr conversion. Such a conversion is ambiguous, as it is unclear if the object’s reference count should be immediately incremented. Rather, use omni::core::steal() and omni::core::borrow() to create an ObjectPtr.
Use get() to return the raw object pointer. The pointer will still be managed by this wrapper.
Use detach() to return and stop managing the raw pointer. When calling detach(), omni::core::IObject::release() will not be called.
Use release() to decrement the raw pointer’s reference count and stop managing the raw pointer.
Warning
ObjectPtr::release()
does not have the same meaning asstd::unique_ptr::release()
.std::unique_ptr::release()
is equivalent toObjectPtr::detach()
.Use as() to cast the pointer to another interface.
Unless otherwise stated, the managed pointer can be
nullptr
.- Thread Safety
All methods are thread safe.
Public Functions
-
inline constexpr
ObjectPtr
(std::nullptr_t = nullptr) noexcept¶ Allow implicit conversion from
nullptr
to an ObjectPtr.
-
inline explicit
ObjectPtr
(T *other)¶ Never call this method as it will terminate the application.
This method is currently needed to satisfy
PyBind
. Note,PyBind
will never actually call this method but will fail with compiler errors if it is not present.OM-18948: Update PyBind to not require a raw pointer to “holder” constructor.
-
inline
ObjectPtr
(T *other, details::BorrowPtrType) noexcept¶ Start managing the given raw pointer. omni::core::IObject::acquire() will be called on the pointer.
Prefer using omni::core::borrow() over this constructor.
-
inline constexpr
ObjectPtr
(T *other, details::StealPtrType) noexcept¶ Start managing the given raw pointer. omni::core::IObject::acquire() will not be called on the pointer.
Prefer using omni::core::steal() over this constructor.
-
template<typename
U
>
inline ObjectPtr &operator=
(const ObjectPtr<U> &other) noexcept¶ Assignment operator.
-
inline explicit
operator bool
() const noexcept¶ Returns true if the managed pointer is not
nullptr
.
-
inline T *
get
() const noexcept¶ Returns the raw pointer. The pointer is still managed by this wrapper.
This method is useful when having to pass raw pointers to ABI functions.
-
inline T **
put
() noexcept¶ Returns a pointer to the managed pointer (which must be
nullptr
).The managed pointer must be
nullptr
, otherwise the function results in undefined behavior.Useful when having to manage pointers output via a function argument list.
void createMyType(MyType** out); // ... ObjectPtr<MyType> ptr; createMyType(ptr.put());
Such methods are rare.
-
inline void
steal
(T *value) noexcept¶ Manage the given pointer. omni::core::IObject::acquire() is not called on the pointer.
See borrow() for a method that does call omni::core::IObject::acquire().
-
inline T *
detach
() noexcept¶ Returns the managed pointer and no longer manages the pointer.
omni::core::IObject::release() is not called on the pointer. Use this method to stop managing the pointer.
-
inline void
borrow
(T *value) noexcept¶ Manage the given pointer. omni::core::IObject::acquire() is called on the pointer.
See steal() for a method that does not call omni::core::IObject::acquire().
-
template<typename
To
>
inline ObjectPtr<To>as
() const noexcept¶ Cast the managed pointer to a new interface type (
To
).nullptr
is returned if the pointer does not implement the interface.
-
template<typename
To
>
inline voidas
(ObjectPtr<To> &to) const noexcept¶ Cast the managed pointer to the type of the given ObjectPtr (e.g.
To
).nullptr
is written toto
if the pointer does not implement the interface.