omni::graph::exec::unstable::INodeGraphDef

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

class INodeGraphDef : public omni::core::Generated<omni::graph::exec::unstable::INodeGraphDef_abi>

Graph definition. Defines work to be done as a graph.

Nodes within a graph represent work to be done. The actual work to be performed is described in a definition . Each node wanting to perform work points to a defintion.

This interface is a subclass of the work definition interface (i.e. omni::graph::exec::unstable::IDef) and extends omni::graph::exec::unstable::IDef with methods to describe work as a graph.

Visually:

../_images/ef-simple-w-defs1.svg

Above, you can see the two types of definitions: opaque definitions (described by omni::graph::exec::unstable::INodeDef) and graph definitions (described by this interface).

Nodes within a graph definition can point to other graph definitions. This composibility is where EF gets its graph of graphs moniker.

Multiple node’s in the execution graph can point to the same instance of a graph definition. This saves both space and graph construction time. However, since each graph definition can be shared, its pointer value cannot be used to uniquely identify its location in the graph. To solve this, when traversing/executing a graph definition, an omni::graph::exec::unstable::ExecutionPath is passed (usually via omni::graph::exec::unstable::ExecutionTask::getUpstreamPath()).

When defining new graph types, it is common to create a new implementation of this interface. See omni::graph::exec:unstable::NodeGraphDef for an implementation of this interface that can be easily inherited from. See Definition Creation for a guide on creating your own graph definition.

How a graph definition’s nodes are traversed during execution is defined by the definition’s omni::graph::exec::unstable::IExecutor. See Execution Concepts for an in-depth guide on how executors and graph definitions work together during execution.

Thread Safety: Since definitions can be shared by multiple nodes, and nodes can be executed in parallel, implementations of this interface should expect its methods to be called in parallel.

Public Functions

inline INode *getRoot() noexcept

Access graph’s root node.

The returned INode. 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 omni::graph::exec::unstable::ITopology *getTopology() noexcept

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(omni::graph::exec::unstable::ExecutionTask &rootTask) noexcept

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 omni::graph::exec::unstable::Status preExecute(omni::graph::exec::unstable::ExecutionTask &info) noexcept

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 omni::graph::exec::unstable::Status postExecute(omni::graph::exec::unstable::ExecutionTask &info) noexcept

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 omni::core::ObjectPtr<omni::graph::exec::unstable::INodeFactory> getNodeFactory() noexcept

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.

Protected Functions

virtual ITopology *getTopology_abi() noexcept = 0

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.

virtual void initializeState_abi(ExecutionTask *rootTask) noexcept = 0

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.

virtual Status preExecute_abi(ExecutionTask *info) noexcept = 0

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.

virtual Status postExecute_abi(ExecutionTask *info) noexcept = 0

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.

virtual INodeFactory *getNodeFactory_abi() noexcept = 0

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.