omni::core::ObjectPtr

template<typename T> class ObjectPtr

Smart pointer wrapper around interface pointers.

This object manages the mundane detail 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.

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.

Warning

ObjectPtr::release() does not have the same meaning as std::unique_ptr::release(). std::unique_ptr::release() is equivalent to ObjectPtr::detach().

Subclassed by omni::python::detail::PyObjectPtr< T >

Public Functions

inline constexpr ObjectPtr(std::nullptr_t = nullptr) noexcept: Allow implicit conversion from nullptr to an ObjectPtr.

inline ObjectPtr(T *other, detail::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, detail::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.

inline ObjectPtr(const ObjectPtr &other) noexcept: Copy constructor.

template<typename U> inline ObjectPtr(const ObjectPtr<U> &other) noexcept: Copy constructor.

template<typename U> inline ObjectPtr(ObjectPtr<U> &&other) noexcept: Move constructor.

inline ~ObjectPtr() noexcept: Destructor. Calls release() on the managed pointer.

inline ObjectPtr &operator=(const ObjectPtr &other) noexcept: Assignment operator.

inline ObjectPtr &operator=(ObjectPtr &&other) noexcept: Move operator.

template<typename U> inline ObjectPtr &operator=(const ObjectPtr<U> &other) noexcept: Assignment operator.

template<typename U> inline ObjectPtr &operator=(ObjectPtr<U> &&other) noexcept: Move operator.

inline explicit operator bool() const noexcept: Returns true if the managed pointer is not nullptr.

inline T *operator->() const noexcept: The managed pointer must not be nullptr.

inline T &operator*() const noexcept: The managed pointer must not be 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 void as(ObjectPtr<To> &to) const noexcept

Cast the managed pointer to the type of the given omni::core::ObjectPtr (e.g. To).

nullptr is written to to if the pointer does not implement the interface.

inline void release() noexcept

Calls release() on the managed pointer and sets the internal pointer to nullptr.

Warning

ObjectPtr::release() does not have the same meaning as std::unique_ptr::release(). std::unique_ptr::release() is equivalent to ObjectPtr::detach().

inline void reset(T *value = nullptr) noexcept

Calls release() on the managed pointer and sets the internal pointer to value.

Equivalent to std::unique_ptr::reset().

Parameters: value – The new value to assign to *this, defaults to nullptr.