ExecutionTask

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

class ExecutionTask

Represents work item generated by an IExecutor and passed to a scheduler for dispatch.

ExecutionTask is a utility class that describes a task to be potentially executed on behalf of a INode in a given IExecutionContext.

ExecutionTask stores four key pieces of information:

• A pointer to the Node to be executed. The pointed to INode contains a pointer to either an INodeDef or NodeGraphDef which contains the computation definition. See ExecutionTask::getNode().

• The unique path to the node. In addition to the INode to be executed, an ExecutionPath to the node’s upstream (i.e. containing) node is stored. Combined, these two pieces of information form a unique id for the node.

  Above, if an ExecutionTask is describing the k node pointed to by the yellow arrow, ExecutionTask::getNode() would point to k and ExecutionTask::getUpstreamPath() would return /f/p. Note, the ExecutionTask::getUpstreamPath() does not store /f/p/k, just /f/p. This is a micro-optimization that allows the same |ExecutionPath| to be reused while visiting nodes within the same INodeGraphDef.

• A pointer to the current execution’s IExecutionContext. Execution always happen in a given context. It’s this context, IExecutionContext, that stores the state of the execution. Multiple entities can be executing a given execution graph , each execution using its own IExecutionContext. In order to understand which of these potentially many executions a task is a part, ExecutionTask stores a reference to the execution’s IExecutionContext. This ExecutionTask::getContext() combined with ExecutionTask::getUpstreamPath() and ExecutionTask::getNode() can be used to access the per-execution state for the node (see OMNI_GRAPH_EXEC_GET_NODE_DATA_AS() and OMNI_GRAPH_EXEC_SET_NODE_DATA()).

• A “tag” to identify a task when multiple tasks are associated with a node. If an INode generates many tasks during execution, ExecutionTask::getTag() can be used to uniquely identify each of the node’s tasks. The semantic meaning of ExecutionTask::getTag() is IExecutor dependent and can be used for purposes other than unique identification.

This class can safely be passed by pointer or value across the ABI. However, due to its size, passing by pointer is recommended.

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

Public Types

enum [anonymous]

Values:

enumerator kEmptyTag

Special value to represent an empty tag.

Public Functions

inline ExecutionTask(

IExecutionContext *context,

INode *node,

const ExecutionPath &upPath,

ExecutionTaskTag tag = kEmptyTag,

) noexcept

Constructor for execution task.

Parameters:

• context – Context in which execution task is created. Task can only access state from this context. omni::core::IObject::acquire() is not called on this context. It is up to the calling code to ensure the context remains valid for the lifetime of the ExecutionTask.

• node – Node holding the execution definition omni::core::IObject::acquire() is not called on this context. It is up to the calling code to ensure the context remains valid for the lifetime of the ExecutionTask.

• upPath – Execution path to the graph owning the node. Node can be executed multiple times with different paths when graph definition is shared.

• tag – Used to identify dynamically generated work items that node can compute.

inline IExecutionContext *getContext() const noexcept

Return context for this task.

The returned IExecutionContext will not have omni::core::IObject::acquire() called before being returned.

Thread Safety

This method is thread safe.

inline INode *getNode() const noexcept

Return node for this task.

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

Thread Safety

This method is thread safe.

inline const ExecutionPath &getUpstreamPath() const noexcept

Return execution path to graph owning the node.

Thread Safety

This method is thread safe.

inline ExecutionTaskTag getTag() const noexcept

Return tag.

Thread Safety

This method is thread safe.

inline bool hasValidTag() const noexcept

Check if this task has a valid tag set. This will mean that a node generates more than one task.

Thread Safety

This method is thread safe.

inline Status getExecutionStatus() const noexcept

Return execution status for this task.

Thread Safety

This method is thread safe.

inline Status execute(

omni::core::ObjectParam<IExecutor> executor,

) noexcept

Execute the task. Will be called by the scheduler when task is dispatched for execution.

Thread Safety

See execution thread safety notes in omni::graph::exec::unstable::IExecutor.

inline void setUserIndex(uint64_t userIndex) noexcept

Set the user defined index.

This index will never be used by the framework, but is a way to pass something into user code via generated task. Mutating this value is allowed as long as it is done via only legal way to access task, i.e. getCurrentTask

Thread Safety

This method is thread safe.

inline uint64_t getUserIndex() const noexcept

Get the user defined index.

This index will never be used by the framework, but is a way to pass something into user code via generated task. Mutating this value is allowed as long as it is done via only legal way to access task, i.e. getCurrentTask

Thread Safety

This method is thread safe.

inline void setExecutionStatus(Status status) noexcept

Sets the status of the task.

This is an internal method and should not be called by users.