ExecutionPath

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

class ExecutionPath

Path representing a unique location of an instantiated node during execution.

The omni::graph::exec::unstable::ExecutionPath class is an efficient utility class used to store the execution path of an omni::graph::exec::unstable::INode. There’s subtlety to what an execution path is. That subtlety is best explained with a diagram:

Above, nodes are labelled with lower-case letters (e.g. a, b, etc.). Node can point to either an omni::graph::exec::unstable::INodeDef (which defines opaque computation) or an omni::graph::exec::unstable::INodeGraphDef (which defines its computation with a subgraph). In the diagram above, omni::graph::exec::unstable::INodeGraphDef objects are labelled with upper-case letters (e.g. X, Y).

Observe that omni::graph::exec::unstable::INodeGraphDef X is used by both nodes e and f. This illustrates that omni::graph::exec::unstable::INodeGraphDef objects can be reused within the graph. This makes sense because omni::graph::exec::unstable::INodeGraphDef is defining computational logic and that logic may be needed in multiple places in the graph (e.g. instancing). Likewise, though not illustrated above, omni::graph::exec::unstable::INodeDef objects can be reused.

Consider node k above (pointed to by the yellow arrow). When k is executing, what is its execution path? One way to describe the path is to store the nodes traversed to get to the node. For instance, /a/c/m/n/h/i/k could be a likely path. Lets call this representation of a path the traversal path.

EF (via omni::graph::exec::unstable::ExecutionPath) does not store traversal paths. Rather, it uses a much more compact representation called the execution path. In the diagram above, the execution path for k is /f/p/k.

omni::graph::exec::unstable::ExecutionPath stores enough information to uniquely identify the node. That’s important, since k is being shared in the diagram above. The execution path /e/k points to the same k node’s memory but logically /e/k and /f/p/k are different nodes. This illustrates the main purpose of this object: omni::graph::exec::unstable::INode, omni::graph::exec::unstable::INodeDef, and omni::graph::exec::unstable::INodeGraphDef objects can not be uniquely identified by their raw pointer value. omni::graph::exec::unstable::ExecutionPath must be used to uniquely identify a node.

omni::graph::exec::unstable::ExecutionPath is often used as a key in a key/value store to access a node’s state data.

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

Unless otherwise noted, methods in this class are not thread-safe.

To reduce the amount of new paths we create, we only create a new path when entering a node graph definition execution. All tasks generated for computing nodes withing the same node graph will point to the same path.

This class can safely be passed by pointer across the ABI. However, since it is not a trivial type, it cannot be passed by value across the ABI. See OMNI_STATIC_ASSERT_CAN_BE_PASSED_BY_VALUE_IN_ABI for details.

Public Functions

inline ExecutionPath() noexcept

Default constructor for an empty path. Consider using sEmpty if you need one.

inline ExecutionPath(const ExecutionPath &src) noexcept

Copy constructor.

inline ExecutionPath &operator=(const ExecutionPath &rhs) noexcept

Assignment operator.

inline explicit ExecutionPath(

omni::core::ObjectParam<INode> node,

) noexcept

Construct a path for a node (used only at the beginning of the execution).

node must not be nullptr.

The given node will not have omni::core::IObject::acquire() called on it.

inline ExecutionPath(

const ExecutionPath &upPath,

omni::core::ObjectParam<INode> node,

) noexcept

Construct a path from an upstream path and a node. Mostly used when entering a node graph definition.

node must not be nullptr.

The given node will not have omni::core::IObject::acquire() called on it.

inline explicit ExecutionPath(

std::initializer_list<omni::core::ObjectParam<INode>> path,

) noexcept

Convenience method for constructing paths from initializer list.

The given nodes must not be nullptr.

The given node will not have omni::core::IObject::acquire() called on it.

inline explicit ExecutionPath(Span<INode*const> path)

Constructs a path from a list of nodes.

The given nodes must not be nullptr.

The given nodes will not have omni::core::IObject::acquire() called on them.

Parameters:

path – The list of nodes to be considered as a path.

inline void push(INode *node) noexcept

Append a node to the path.

The given node is not internally acquired and it is up to the calling code to ensure the node remains alive while in use by this object.

Thread Safety

This method is not thread safe.

inline ExecutionPath copyWithoutTop() const noexcept

Return a new path with a last node removed.

Thread Safety

This method is not thread safe.

inline ExecutionPathHash getHash() const noexcept

Compute unique index using pairing function and unique indexes of nodes (within owning topology)

This is one strategy to generate a hash for a path. Other hashing strategies can be built outside of the class and used for example when retrieving state from execution context.

The computed hash is internally cached.

Thread Safety

This method is thread safe.

inline ExecutionPathHash getHashWith(

omni::core::ObjectParam<INode> node,

) const noexcept

Compute unique index using pairing function and unique indexes of nodes (within owning topology)

Thread Safety

This method is thread safe.

Parameters:

node – Include given node as the last node in the path. This allows us to avoid creating a new path when fetching a state for an execution task.

inline bool isEmpty() const noexcept

Check if path is empty.

Thread Safety

This method is thread safe.

inline Span<INode*const> getData() const noexcept

Access to underlying path container.

Thread Safety

This method is not thread safe.

inline INode *getTop() const noexcept

Return the node at the top of the stack.

Undefined behavior if the stack is empty.

Thread Safety

This method is not thread safe.

Public Static Functions

static inline const ExecutionPath &getEmpty() noexcept

An instance of an empty path.

Thread Safety

This method is thread safe.

Warning

A different empty path may be returned over multiple calls of this method. Do not rely on using a pointer to the returned object to check if another path is the empty path. Rather, use the isEmpty() method to check if a path is empty.

static inline ExecutionPathHash pairingFunction(

ExecutionPathHash a,

ExecutionPathHash b,

)

Pairing function used by the hashing algorithm.

Thread Safety

This method is thread safe.