omni::graph::exec::unstable::NodeT

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

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

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

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

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

This class can be seen as a way to provide a reasonable, default implementation of both omni::graph::exec::unstable::INode and omni::graph::exec::unstable::IGraphBuilderNode. 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 node. See Private Interfaces for details.

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

Storing authoring data in omni::graph::exec::unstable::NodeGraphDefT during graph construction is another way to link authoring data and the Execution Framework. Again, the user must be mindful that definitions can be shared across multiple nodes in the execution graph.

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 virtual ~NodeT()

Destructor.

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 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

template<typename T>
static inline omni::core::ObjectPtr<NodeT> create(T &&graphOrTopology, const carb::cpp::string_view &idName)

Constructor of a node with an empty definition.

The given graph or topology must not be nullptr.

The given name must not be nullptr.

A valid pointer is always returned.

template<typename T, typename D>
static inline omni::core::ObjectPtr<NodeT> create(T &&graphOrTopology, D &&def, const carb::cpp::string_view &idName)

Constructor of a node with a definition (can be a base definition IDef, an opaque node definition INodeDef, or a node graph definition INodeGraphDef).

The given graph or topology must not be nullptr.

The given name must not be nullptr.

A valid pointer is always returned.

Protected Functions

inline ITopology *getTopology_abi() noexcept override

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 ConstName *getName_abi() noexcept override

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 NodeIndexInTopology getIndexInTopology_abi() noexcept override

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

Thread Safety

This method is thread safe.

inline Span<INode*const> getParents_abi() noexcept override

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 Span<INode*const> getChildren_abi() noexcept override

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

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

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.

Note

This method is called in the destructor and therefore must be marked as final

inline virtual void validateOrResetTopology_abi() 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 IDef *getDef_abi() noexcept override

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 INodeDef *getNodeDef_abi() noexcept override

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 INodeGraphDef *getNodeGraphDef_abi() noexcept override

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 _addParent_abi(IGraphBuilderNode *parent) noexcept override

Adds the given node as a parent (i.e. upstream) of this node.

omni::core::IObject::acquire() is not called on the given node. It is up to the calling code to ensure the node persists while in use by this interface.

parent must not be nullptr.

It is undefined behavior to add a parent multiple times to a node.

Do not directly call this method. Instead, call omni::graph::exec::unstable::IGraphBuilder::connect().

Thread Safety

This method is not thread safe.

inline void _removeParent_abi(IGraphBuilderNode *parent) noexcept override

Removes the given node as a parent.

It is not an error if the given node is not a parent.

The given node may be nullptr.

Do not directly call this method. Instead, call omni::graph::exec::unstable::IGraphBuilder::disconnect().

Thread Safety

This method is not thread safe.

inline void _addChild_abi(IGraphBuilderNode *child) noexcept override

Adds the given node as a child (i.e. downstream) of this node.

omni::core::IObject::acquire() is not called on the given node. It is up to the calling code to ensure the node persists while in use by this interface.

child must not be nullptr.

It is undefined behavior to add a child multiple times to a node.

Do not directly call this method. Instead, call omni::graph::exec::unstable::IGraphBuilder::connect().

Thread Safety

This method is not thread safe.

inline void _removeChild_abi(IGraphBuilderNode *child) noexcept override

Removes the given node as a child.

It is not an error if the given node is not a parent.

The given node may not be nullptr.

Do not directly call this method. Instead, call omni::graph::exec::unstable::IGraphBuilder::disconnect().

Thread Safety

This method is not thread safe.

inline void _removeInvalidParents_abi() noexcept override

Remove from this node’s parent list any nodes that no longer exist in current topology, i.e are invalid.

omni::core::IObject::release() is not called on the invalid nodes.

Do not directly call this method. It is used internally by omni::graph::exec::unstable::IGraphBuilder.

Thread Safety

This method is not thread safe.

inline void _removeInvalidChildren_abi() noexcept override

Remove from this node’s children list any nodes that no longer exist in current topology, i.e are invalid.

omni::core::IObject::release() is not called on the invalid nodes.

Do not directly call this method. It is used internally by omni::graph::exec::unstable::IGraphBuilder.

Thread Safety

This method is not thread safe.

inline void _invalidateConnections_abi() noexcept override

Invalidate all children and parents connections by invalidating the topology stamp this node is synchronized with.

Do not directly call this method. It is used internally by omni::graph::exec::unstable::IGraphBuilder.

Thread Safety

This method is thread safe.

Warning

This only removes connections on a single node. The topology has bi-directional connections for every node with the exception of the connection with the root node.

inline void setCycleParentCount_abi(uint32_t count) noexcept override

Sets the number of parents who are a part of cycle.

Thread Safety

This method is not thread safe.

inline void _setNodeDef_abi(INodeDef *nodeDef) noexcept override

Sets the definition for this node.

If a definition is already set, it will be replaced by the given definition.

The given definition may be nullptr.

omni::core::IObject::acquire() is called on the given pointer.

See also omni::graph::exec::unstable::IGraphBuilderNode::_setNodeGraphDef().

Do not directly call this method. Instead, call omni::graph::exec::unstable::IGraphBuilder::setNodeDef().

Thread Safety

This method is not thread safe.

inline void _setNodeGraphDef_abi(INodeGraphDef *nodeGraphDef) noexcept override

Sets the definition for this node.

If a definition is already set, it will be replaced by the given definition.

The given definition may be nullptr.

omni::core::IObject::acquire() is called on the given pointer.

See also omni::graph::exec::unstable::IGraphBuilderNode::_setNodeDef().

Do not directly call this method. Instead, call omni::graph::exec::unstable::IGraphBuilder::setNodeGraphDef().

Thread Safety

This method is not thread safe.

inline void _clearDef_abi() noexcept override

Unsets this node’s definition.

If the definition is already nullptr, this method does nothing.

Do not directly call this method. Instead, call omni::graph::exec::unstable::IGraphBuilder::clearDef().

Thread Safety

This method is not thread safe.

inline IGraphBuilderNode *getParentAt_abi(uint64_t index) noexcept override

Access the parent at the given index.

It is an error if the the given index is greater than the parent count.

See omni::graph::exec::unstable::IGraphBuilderNode::getParentCount().

Consider using omni::graph::exec::unstable::IGraphBuilderNode::getParents() for a modern C++ wrapper to this method.

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

The returned pointer will not be nullptr.

Thread Safety

This method is not thread safe.

inline uint64_t getParentCount_abi() noexcept override

Returns the number of parents.

Thread Safety

This method is not thread safe.

inline IGraphBuilderNode *getChildAt_abi(uint64_t index) noexcept override

Access the child at the given index.

It is an error if the the given index is greater than the child count.

See omni::graph::exec::unstable::IGraphBuilderNode::getChildCount().

Consider using omni::graph::exec::unstable::IGraphBuilderNode::getChildren() for a modern C++ wrapper to this method.

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

The returned pointer will not be nullptr.

Thread Safety

This method is not thread safe.

inline uint64_t getChildCount_abi() noexcept override

Returns the number of children.

Thread Safety

This method is not thread safe.

inline bool hasChild_abi(IGraphBuilderNode *node) noexcept override

Returns true if the given node is an immediate child of this node.

node may be nullptr.

Thread Safety

This method is not thread safe.

inline bool isRoot_abi() noexcept override

Returns true if this node is the root of the topology.

Thread Safety

This method is not thread safe.

inline IGraphBuilderNode *getRoot_abi() noexcept override

Returns the root node of the topology of which this node is a part.

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

The returned pointer will not be nullptr.

Thread Safety

This method is not thread safe.

inline NodeT(ITopology *topology, const carb::cpp::string_view &idName) noexcept

Constructor.

inline NodeT(ITopology *topology, INodeGraphDef *nodeGraphDef, const carb::cpp::string_view &idName) noexcept

Constructor.

inline NodeT(ITopology *topology, INodeDef *nodeDef, const carb::cpp::string_view &idName) noexcept

Constructor.

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.