omni::graph::exec::unstable::INode

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

class INode : public omni::core::Generated<omni::graph::exec::unstable::INode_abi>

Represents work in a graph. Nodes point to a shared execution definition to state the actual work.

omni::graph::exec::unstable::INode is the main structural component used to build a graph’s topology. omni::graph::exec::unstable::INode stores edges to parents (i.e. predecessors) and children (i.e. successors). These edges set an ordering between nodes. See omni::graph::exec::unstable::INode::getParents() and omni::graph::exec::unstable::INode::getChildren() respectively.

A node represents work to be performed. The description of the work to be performed is stored in a definition (i.e. omni::graph::exec::unstable::IDef). Each node wishing to perform work points to a definition (see omni::graph::exec::unstable::INode::getDef()).

The definition to which a node points can be one of two types. The first type, omni::graph::exec::unstable::INodeDef, defines work opaquely (i.e. EF is unable to view the work definition and potentially optimize it). The second type, omni::graph::exec::unstable::INodeGraphDef, defines work with a graph. This last representation is the most power as it allows for both extensibilty and composibility in EF.

Above, we see that nodes point to graph definitions, which contain other nodes that point to other graph definitions. This structure of graphs pointing to other graphs is where EF gets its graph of graphs name.

Not all nodes will point to a definition. For example, the root node in each graph definition will not point to a definition.

A node is always part of a graph definition and the graph definition’s executor is responsible for orchestrating and generating work to the scheduler.

Node’s within a graph definition are assigned a unique index, between zero and the number of nodes in the definition. This index is often used as a lookup into transient arrays used to store state during graph traversals. See omni::graph::exec::unstable::INode::getIndexInTopology().

Nodes have a notion of validity. See Graph Invalidation for details.

omni::graph::exec::unstable::INode does not contain methods for either settings the node’s definition or connecting nodes to each other. This functionality is reserved for omni::graph::exec::unstable::IGraphBuilder. See Graph Construction for details.

See Graph Concepts for a guide on how this object relates to other objects in the Execution Framework.

See Execution Concepts for an in-depth guide on how this object is used during execution.

Users may wish to implement this interface to store meaningful authoring level data in EF. For example, OmniGraph uses an implementation of this node to store graph instancing information. See omni::graph::exec::unstable::Node for a concrete implementation of this interface suitable for inheriting.

Public Types

using NodeArray = Span<INode*const>

Stores the list of parents and children.

Public Functions

inline INode *getRoot() noexcept

Returns the root of the graph definition of which this node is a part.

Thread Safety

This method is thread safe.

inline bool isRoot() noexcept

Check if this node is the root of the graph/topology.

Thread Safety

This method is thread safe.

inline bool hasParent(omni::core::ObjectParam<INode> parent) noexcept

Check if a given node is a parent of this node.

The given node may be nullptr.

Thread Safety

This method makes no guarantees on thread safety. However, in practice, accessing the parents during execution is safe as the list of parents is not expected to change during execution. Accessing the parents during graph construction requires coordination with the passes building the graph.

inline bool hasChild(omni::core::ObjectParam<INode> child) noexcept

Check if a given node is a child of this node.

The given node may be nullptr.

Thread Safety

This method makes no guarantees on thread safety. However, in practice, accessing the children during execution is safe as the list of children is not expected to change during execution. Accessing the children during graph construction requires coordination with the passes building the graph.

inline omni::graph::exec::unstable::ITopology *getTopology() noexcept

Access topology owning this node.

The returned pointer will not be nullptr.

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

Thread Safety

This method is thread safe.

inline const omni::graph::exec::unstable::ConstName &getName() noexcept

Access node’s unique identifier name.

The lifetime of the returned object is tied to this node.

Thread Safety

This method is thread safe.

inline omni::graph::exec::unstable::NodeIndexInTopology getIndexInTopology() noexcept

Access nodes unique index withing owning topology. Index will be always smaller than topology size.

Thread Safety

This method is thread safe.

inline omni::graph::exec::unstable::Span<omni::graph::exec::unstable::INode*const> getParents() noexcept

Access parents.

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

Thread Safety

This method makes no guarantees on thread safety. However, in practice, accessing the parents during execution is safe as the list of parents is not expected to change during execution. Accessing the parents during graph construction requires coordination with the passes building the graph.

inline omni::graph::exec::unstable::Span<omni::graph::exec::unstable::INode*const> getChildren() noexcept

Access children.

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

Thread Safety

This method makes no guarantees on thread safety. However, in practice, accessing the children during execution is safe as the list of children is not expected to change during execution. Accessing the children during graph construction requires coordination with the passes building the graph.

inline uint32_t getCycleParentCount() noexcept

Return number of parents that cause cycles within the graph during traversal over this node.

Thread Safety

This method makes no guarantees on thread safety. However, in practice, accessing this count during execution is safe as the cycle count is expected to be computed during graph construction. Accessing the count during graph construction requires coordination with the passes building the graph.

inline bool isValidTopology() noexcept

Check if topology/connectivity of nodes is valid within current topology version.

See Graph Invalidation for details on invalidation.

Thread Safety

This method is not thread safe.

inline void validateOrResetTopology() noexcept

Check if this node is valid in the topology, dropping all connections if it is not.

This method checks if the node is valid in the topology (i.e. checks the node’s topology stamp with the topology). If it is not valid, all parent and child connections are removed and the cycle count is set back to zero.

If the node is valid in the topology, this method does nothing.

See Graph Invalidation to better understand stamps, topologies, and invalidation.

Thread Safety

This method is not thread safe.

inline omni::graph::exec::unstable::IDef *getDef() noexcept

Access the node’s definition (can be empty).

When you wish to determine if the attached definition is either opaque or a graph, consider calling omni::graph::exec::unstable::INode::getNodeDef() or omni::graph::exec::unstable::INode::getNodeGraphDef() rather than this method.

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

Thread Safety

This method is thread safe during execution since the definition is not expected to change during execution. During construction, access to this method must be coordinated between the passes building the graph.

inline omni::graph::exec::unstable::INodeDef *getNodeDef() noexcept

Access node definition (can be empty).

If the returned pointer is nullptr, either the definition does not implement omni::graph::exec::unstable::INodeDef or there is no definition attached to the node.

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

Also see omni::graph::exec::unstable::INode::getDef() and omni::graph::exec::unstable::INode::getNodeGraphDef().

Thread Safety

This method is thread safe during execution since the definition is not expected to change during execution. During construction, access to this method must be coordinated between the passes building the graph.

inline omni::graph::exec::unstable::INodeGraphDef *getNodeGraphDef() noexcept

Access node’s graph definition (can be empty)

The returned graph definition pointer is the graph definition which defines the work this node represents. The returned pointer is not the graph definition that contains this node.

If the returned pointer is nullptr, either the definition does not implement omni::graph::exec::unstable::INodeGraphDef or there is no definition attached to the node.

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

Also see omni::graph::exec::unstable::INode::getDef() and omni::graph::exec::unstable::INode::getNodeDef().

Thread Safety

This method is thread safe during execution since the definition is not expected to change during execution. During construction, access to this method must be coordinated between the passes building the graph.

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 ITopology *getTopology_abi() noexcept = 0

Access topology owning this node.

The returned pointer will not be nullptr.

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

Thread Safety

This method is thread safe.

virtual const ConstName *getName_abi() noexcept = 0

Access node’s unique identifier name.

The lifetime of the returned object is tied to this node.

Thread Safety

This method is thread safe.

virtual NodeIndexInTopology getIndexInTopology_abi() noexcept = 0

Access nodes unique index withing owning topology. Index will be always smaller than topology size.

Thread Safety

This method is thread safe.

virtual Span<INode*const> getParents_abi() noexcept = 0

Access parents.

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

Thread Safety

This method makes no guarantees on thread safety. However, in practice, accessing the parents during execution is safe as the list of parents is not expected to change during execution. Accessing the parents during graph construction requires coordination with the passes building the graph.

virtual Span<INode*const> getChildren_abi() noexcept = 0

Access children.

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

Thread Safety

This method makes no guarantees on thread safety. However, in practice, accessing the children during execution is safe as the list of children is not expected to change during execution. Accessing the children during graph construction requires coordination with the passes building the graph.

virtual uint32_t getCycleParentCount_abi() noexcept = 0

Return number of parents that cause cycles within the graph during traversal over this node.

Thread Safety

This method makes no guarantees on thread safety. However, in practice, accessing this count during execution is safe as the cycle count is expected to be computed during graph construction. Accessing the count during graph construction requires coordination with the passes building the graph.

virtual bool isValidTopology_abi() noexcept = 0

Check if topology/connectivity of nodes is valid within current topology version.

See Graph Invalidation for details on invalidation.

Thread Safety

This method is not thread safe.

virtual void validateOrResetTopology_abi() noexcept = 0

Check if this node is valid in the topology, dropping all connections if it is not.

This method checks if the node is valid in the topology (i.e. checks the node’s topology stamp with the topology). If it is not valid, all parent and child connections are removed and the cycle count is set back to zero.

If the node is valid in the topology, this method does nothing.

See Graph Invalidation to better understand stamps, topologies, and invalidation.

Thread Safety

This method is not thread safe.

virtual IDef *getDef_abi() noexcept = 0

Access the node’s definition (can be empty).

When you wish to determine if the attached definition is either opaque or a graph, consider calling omni::graph::exec::unstable::INode::getNodeDef() or omni::graph::exec::unstable::INode::getNodeGraphDef() rather than this method.

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

Thread Safety

This method is thread safe during execution since the definition is not expected to change during execution. During construction, access to this method must be coordinated between the passes building the graph.

virtual INodeDef *getNodeDef_abi() noexcept = 0

Access node definition (can be empty).

If the returned pointer is nullptr, either the definition does not implement omni::graph::exec::unstable::INodeDef or there is no definition attached to the node.

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

Also see omni::graph::exec::unstable::INode::getDef() and omni::graph::exec::unstable::INode::getNodeGraphDef().

Thread Safety

This method is thread safe during execution since the definition is not expected to change during execution. During construction, access to this method must be coordinated between the passes building the graph.

virtual INodeGraphDef *getNodeGraphDef_abi() noexcept = 0

Access node’s graph definition (can be empty)

The returned graph definition pointer is the graph definition which defines the work this node represents. The returned pointer is not the graph definition that contains this node.

If the returned pointer is nullptr, either the definition does not implement omni::graph::exec::unstable::INodeGraphDef or there is no definition attached to the node.

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

Also see omni::graph::exec::unstable::INode::getDef() and omni::graph::exec::unstable::INode::getNodeDef().

Thread Safety

This method is thread safe during execution since the definition is not expected to change during execution. During construction, access to this method must be coordinated between the passes building the graph.

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.