omni::graph::exec::unstable::IBase

Defined in omni/graph/exec/unstable/IBase.h

class IBase : public omni::core::Generated<omni::graph::exec::unstable::IBase_abi>

Base class for all omni::graph::exec objects.

This interface provides cheap casting between interfaces without calling omni::core::IObject::acquire().

The Execution Framework has a rich hierarchy of interfaces. Users are expected to extend this hierarchy to define custom behavior for their part of the execution graph. These extensions are likely to implement a suite of interfaces, many of which will want to access the custom functionality provided by the other interfaces in the suite.

As an example, a user can create a custom omni::graph::exec::unstable::IExecutor (i.e. IMyExecutor), that would like to access data on their custom omni::graph::exec::unstable::INode objects (i.e. IMyNode). The core framework does not know about the IMyNode interface and will only pass omni::graph::exec::unstable::INode objects to IMyExecutor. To access the custom IMyNode functionality, IMyExecutor can call omni::core::cast() on the the given omni::graph::exec::unstable::INode objects to cast to IMyNode. Unlike dynamic_cast or reinterpret_cast, omni::core::cast() is ABI-safe.

Unfortunately, omni::core::cast(), by contract, internally calls omni::core::IObject::acquire() on the returned pointer. This cost is small, but can add up in hot code paths.

The purpose of omni::graph::exec::unstable::IBase is to provide a casting method that does not call omni::core::IObject::acquire(). This micro optimization helps in hot code paths, albeit with the added danger of potentially mismanaging the object’s ref count.

The cheap casting this interface provides should be accessed with omni::graph::exec::unstable::cast(). To avoid mismanaging the object’s ref count, it is recommended to always use auto when storing the results of calling methods in the Execution Framework.

Public Functions

inline void *castWithoutAcquire(omni::core::TypeId id) noexcept

Casts this object to the type described the the given id.

Returns nullptr if the cast was not successful.

Unlike omni::core::IObject::cast(), this casting method does not call omni::core::IObject::acquire().

Thread Safety: This method is thread safe.

inline uint32_t getUseCount() noexcept

Returns the number of different instances (this included) referencing the current object.

Thread Safety: This method is thread safe.

inline void *cast(omni::core::TypeId id) noexcept

Returns a pointer to the interface defined by the given type id if this object implements the type id’s interface.

Objects can support multiple interfaces, even interfaces that are in different inheritance chains.

The returned object will have omni::core::IObject::acquire() called on it before it is returned, meaning it is up to the caller to call omni::core::IObject::release() on the returned pointer.

The returned pointer can be safely reinterpret_cast<> to the type id’s C++ class. For example, “omni.windowing.IWindow” can be cast to omni::windowing::IWindow.

Do not directly use this method, rather use a wrapper function like omni::core::cast() or omni::core::ObjectPtr::as().

Thread Safety: This method is thread safe.

inline void acquire() noexcept

Increments the object’s reference count.

Objects may have multiple reference counts (e.g. one per interface implemented). As such, it is important that you call omni::core::IObject::release() on the same pointer from which you called omni::core::IObject::acquire().

Do not directly use this method, rather use omni::core::ObjectPtr, which will manage calling omni::core::IObject::acquire() and omni::core::IObject::release() for you.

Thread Safety: This method is thread safe.

inline void release() noexcept

Decrements the objects reference count.

Most implementations will destroy the object if the reference count reaches 0 (though this is not a requirement).

Objects may have multiple reference counts (e.g. one per interface implemented). As such, it is important that you call omni::core::IObject::release() on the same pointer from which you called omni::core::IObject::acquire().

Do not directly use this method, rather use omni::core::ObjectPtr, which will manage calling omni::core::IObject::acquire() and omni::core::IObject::release() for you.

Thread Safety: This method is thread safe.

Protected Functions

virtual void *castWithoutAcquire_abi(omni::core::TypeId id) noexcept = 0

Casts this object to the type described the the given id.

Returns nullptr if the cast was not successful.

Unlike omni::core::IObject::cast(), this casting method does not call omni::core::IObject::acquire().

Thread Safety: This method is thread safe.

virtual uint32_t getUseCount_abi() noexcept = 0

Returns the number of different instances (this included) referencing the current object.

Thread Safety: This method is thread safe.

virtual void *cast_abi(TypeId id) noexcept = 0

Returns a pointer to the interface defined by the given type id if this object implements the type id’s interface.

Objects can support multiple interfaces, even interfaces that are in different inheritance chains.

The returned object will have omni::core::IObject::acquire() called on it before it is returned, meaning it is up to the caller to call omni::core::IObject::release() on the returned pointer.

The returned pointer can be safely reinterpret_cast<> to the type id’s C++ class. For example, “omni.windowing.IWindow” can be cast to omni::windowing::IWindow.

Do not directly use this method, rather use a wrapper function like omni::core::cast() or omni::core::ObjectPtr::as().

Thread Safety: This method is thread safe.

virtual void acquire_abi() noexcept = 0

Increments the object’s reference count.

Objects may have multiple reference counts (e.g. one per interface implemented). As such, it is important that you call omni::core::IObject::release() on the same pointer from which you called omni::core::IObject::acquire().

Do not directly use this method, rather use omni::core::ObjectPtr, which will manage calling omni::core::IObject::acquire() and omni::core::IObject::release() for you.

Thread Safety: This method is thread safe.

virtual void release_abi() noexcept = 0

Decrements the objects reference count.

Most implementations will destroy the object if the reference count reaches 0 (though this is not a requirement).

Objects may have multiple reference counts (e.g. one per interface implemented). As such, it is important that you call omni::core::IObject::release() on the same pointer from which you called omni::core::IObject::acquire().

Do not directly use this method, rather use omni::core::ObjectPtr, which will manage calling omni::core::IObject::acquire() and omni::core::IObject::release() for you.

Thread Safety: This method is thread safe.