NodeGraphDefT#

Fully qualified name: omni::graph::exec::unstable::NodeGraphDefT

template<typename ...Bases> class NodeGraphDefT : public omni::graph::exec::unstable::Implements<Bases...>#

Concrete implementation of omni::graph::exec::unstable::INodeGraphDef.

This template is a concrete implementation of omni::graph::exec::unstable::INodeGraphDef. In many cases, instantiating omni::graph::exec::unstable::NodeGraphDef (which is instance of this template) will suffice.

See omni::graph::exec::unstable::INodeGraphDef for documentation on the purpose of graph definitions in the Execution Framework.

This class can be seen as a way to provide a reasonable, default implementation of both omni::graph::exec::unstable::INodeGraphDef and omni::graph::exec::unstable::INodeGraphDefDebug. The template arguments allow the developer to further customize the interfaces this class implements. A common pattern seen in the Execution Framework is to define a private interface to attach authoring data to a definition. See Private Interfaces for details.

Storing authoring data in the graph definition during graph construction is one way to link authoring data and the Execution Framework. However, the user must be mindful that definitions can be shared across multiple nodes in the execution graph.

During graph construction, authoring data can also be stored in omni::graph::exec::unstable::NodeT. When storing data in omni::graph::exec::unstable::NodeT, the user must again be mindful that a node may be a part of a definition that is shared.

omni::graph::exec::unstable::IExecutionContext is another place to store data. Rather than storing authoring data, omni::graph::exec::unstable::IExecutionContext is designed to store execution/evaluation data keyed on each node’s unique omni::graph::exec::unstable::ExecutionPath. Since definitions can be shared between nodes, each node’s omni::graph::exec::unstable::ExecutionPath is necessary to uniquely identify the “instance” of any given node.

Public Functions

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.

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#: See omni::core::IObject::cast.

inline void *castWithoutAcquire(omni::core::TypeId id) noexcept#: See omni::graph::exec::unstable::IBase_abi::castWithoutAcquire_abi.

Public Static Functions

static inline omni::core::ObjectPtr<NodeGraphDefT> create( omni::core::ObjectParam<IGraph> owner, const carb::cpp::string_view &definitionName, ) noexcept#

Construct graph node definition with default executor.

This method never returns nullptr.

Parameters:

owner – Execution graph having this graph as part of the global topology. Must not be nullptr.
definitionName – Definition name is considered as a token that transformation passes can register against. Must not be nullptr.

static inline omni::core::ObjectPtr<NodeGraphDefT> create( omni::core::ObjectParam<IGraph> owner, ExecutorFactory executorFactory, const carb::cpp::string_view &definitionName, ) noexcept#

Construct graph node definition with the given executor factory.

This method never returns nullptr.

Parameters:

owner – Execution graph having this graph as part of the global topology. Must not be nullptr.
executorFactory – Factory returning executor for this graph.
definitionName – Definition name is considered as a token that transformation passes can register against. Must not be nullptr.

Protected Functions

inline Status execute_abi(ExecutionTask *info) noexcept override#

Execute the node definition.

The given task must not be nullptr.

Prefer calling omni::graph::exec::unstable::ExecutionTask::execute() rather than this method as omni::graph::exec::unstable::ExecutionTask::execute() populates information such as omni::graph::exec::unstable::getCurrentTask().

See Error Handling to understand the error handling/reporting responsibilities of implementors of this method.

This implementation delegates execution omni::graph::exec::unstable::IExecutor. The lifetime of an executor is only for a single execution and any state that needs to persist longer than a single execution must be written with omni::graph::exec::unstable::IExecutionContext::setNodeData_abi().

Thread Safety: See thread safety information in interface description.

inline SchedulingInfo getSchedulingInfo_abi( const ExecutionTask *info, ) noexcept override#

Provides runtime information about scheduling constraints for a given task/node.

The provided omni::graph::exec::unstable::ExecutionTask can be used to determine the path of the current definition.

The given task must not be nullptr.

Thread Safety: See thread safety information in interface description.

inline const ConstName *getName_abi() noexcept override#

Return unique definition identifier.

The returned pointer is never nullptr. The lifetime of the data returned is tied to the lifetime of this object.

Thread Safety: See thread safety information in interface description.

inline ITopology *getTopology_abi() noexcept override#

Return this graph’s topology object.

Each omni::graph::exec::unstable::INodeGraphDef owns a omni::graph::exec::unstable::ITopology.

The returned omni::graph::exec::unstable::ITopology will not have omni::core::IObject::acquire() called before being returned.

This method will never return nullptr.

Thread Safety: This method is thread safe.

inline void initializeState_abi( ExecutionTask *rootTask, ) noexcept override#

Initialize the state of the graph.

It is up to the implementation of the graph type to decide whether this call needs to be propagated over all nodes within the graph or a single shared state is owned by the graph.

Thread Safety: See thread safety information in interface description.

Parameters:: rootTask – State will be initialized for every instance of this graph. Root task will provide a path to allow discovery of the state. Must not be nullptr.

inline Status preExecute_abi(ExecutionTask *info) noexcept override#

Pre-execution call that can be used to setup the graph state prior to execution or entirely skip the execution.

The given task must not be nullptr.

See Error Handling to understand the error handling/reporting responsibilities of implementors of this method.

Thread Safety: See thread safety information in interface description.

inline Status postExecute_abi(ExecutionTask *info) noexcept override#

Post-execution call can be used to finalize the execution, e.g. transfer computation results to consumers.

The given task must not be nullptr.

See Error Handling to understand the error handling/reporting responsibilities of implementors of this method.

Thread Safety: See thread safety information in interface description.

inline INodeFactory *getNodeFactory_abi() noexcept override#

Acquire factory object allowing for allocating new node instances for this graph definition.

The returned factory may be nullptr when the graph definition does not allow allocating new nodes outside of pass that constructed the definition in the first place.

The returned omni::graph::exec::unstable::INodeFactory will have omni::core::IObject::acquire() called before being returned.

Thread Safety: Accessing node factory is thread-safe but mutating graphs topology is not. This includes node creation.

inline uint64_t getExecutionCount_abi() noexcept override#

Returns the current execution count. A value of 0 means the graph is not executing.

Thread Safety: This method is thread safe.

inline void incrementExecutionCount_abi() noexcept override#

Increments the execution count.

Prefer using omni::graph::exec::unstable::ScopedExecutionDebug rather than directly calling this method.

Thread Safety: This method is thread safe.

inline void decrementExecutionCount_abi() noexcept override#

Decrements the execution count.

Prefer using omni::graph::exec::unstable::ScopedExecutionDebug rather than directly calling this method.

The caller must not decrement the execution count below zero.

Thread Safety: This method is thread safe.

inline NodeGraphDefT( omni::core::ObjectParam<IGraph> owner, const carb::cpp::string_view &definitionName, ) noexcept#: Constructor with a default executor.

inline NodeGraphDefT( omni::core::ObjectParam<IGraph> owner, ExecutorFactory &&executorFactory, const carb::cpp::string_view &definitionName, ) noexcept#: Constructor with a custom executor.

inline void acquire_abi() noexcept override#

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_abi() noexcept override#

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.

inline uint32_t getUseCount_abi() noexcept override#: Returns the number of different instances (this included) referencing the current object.

inline void *cast_abi(omni::core::TypeId id) noexcept override#

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 *castWithoutAcquire_abi( omni::core::TypeId id, ) noexcept override#

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.

Protected Attributes

std::atomic<uint32_t> m_refCount#: Reference count.