omni::python::detail::PyObjectPtr

template<typename T> class PyObjectPtr : public omni::core::ObjectPtr<T>

pybind11 “holder” for objects inherited from omni::core::ObjectPtr.

By default, omni::core::ObjectPtr does not have a constructor that accepts a lone pointer. This is because it is ambiguous if addReference() should be called on the pointer. Unfortunately, pybind11 expects such a constructor to exists. The purpose of this class is provide the constructor pybind11 expects.

Note that we’re careful to never generate bindings that call the ambiguous constructor. To protect against future breakage, OMNI_FATAL_UNLESS is used to flag bad code is being generated. Unfortunately, this check must be performed at runtime.

An future alternative to this approach is to patch pybind11

OM-18948: Update PyBind to not require a raw pointer to “holder” constructor.

Public Functions

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

inline explicit PyObjectPtr(T*): Never call this method as it will terminate the application. See class description for rationale.

inline PyObjectPtr(const core::ObjectPtr<T> &other) noexcept: Copy constructor.

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

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

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.