omni::graph::exec::unstable::IExecutionCurrentThread

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

class IExecutionCurrentThread : public omni::core::Generated<omni::graph::exec::unstable::IExecutionCurrentThread_abi>

Encapsulates the execution state for the current thread allowing callers to determine quantities like the omni::graph::exec::unstable::ExecutionTask currently executing on the thread.

Because methods in this interface return thread local data, all methods in this interface are thread safe.

This interface is usually accessed as a singleton via one of the following helper methods:

• omni::graph::exec::unstable::getCurrentTask()

• omni::graph::exec::unstable::getCurrentExecutor()

This interface contains methods for graph and task execution. Users should not call these methods directly. See the methods’ docs below for the correct way to perform execution.

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

Thread Safety

Methods in this interface are thread safe.

Public Functions

inline omni::graph::exec::unstable::Status executeGraph(omni::core::ObjectParam<omni::graph::exec::unstable::IGraph> graph, omni::core::ObjectParam<omni::graph::exec::unstable::IExecutionContext> context) noexcept

Executes the given omni::graph::exec::unstable::IGraph on the current thread.

Do not call this function directly, rather, call omni::graph::exec::unstable::IExecutionContext::execute().

From an ABI point-of-view, the purpose of this method is to handle the special case of the top-level omni::graph::exec::unstable::INodeGraphDef being contained by omni::graph::exec::unstable::IGraph rather than pointed to by a node in another omni::graph::exec::unstable::INodeGraphDef. Meaningful values are set for the threads current task and executor (see omni::graph::exec::unstable::getCurrentTask() and omni::graph::exec::unstable::getCurrentExecutor()).

For further details on the meaning of the returned value, see Error Handling .

Thread Safety

This method is thread safe.

inline omni::graph::exec::unstable::Status execute(omni::graph::exec::unstable::ExecutionTask &task, omni::core::ObjectParam<omni::graph::exec::unstable::IExecutor> executor) noexcept

Executes the given task on the current thread.

Do not call this function directly, rather, call omni::graph::exec::unstable::ExecutionTask::execute().

This method executes the definition of the node pointed to by the given task. Importantly, this method sets thread local data to track the currently running task and executor (see omni::graph::exec::unstable::getCurrentTask() and omni::graph::exec::unstable::getCurrentExecutor()).

Both the given task and executor must not be nullptr.

The node in the given task will be executed and its status set. This status can be retrieved with omni::graph::exec::unstable::ExecutionTask::getExecutionStatus().

Once the node has been executed, omni::graph::exec::unstable::IExecutor::continueExecute() is called and its status returned. The returned status may not be the same as the status set on the task that was executed.

For further details on the meaning of the returned value, see Error Handling .

It is not an error if the given node does not have an attached definition.

Thread Safety

This method is thread safe.

inline omni::graph::exec::unstable::ExecutionTask *getCurrentTask() noexcept

Access the task currently executing on the current thread.

This is useful when needing to access execution context state without having to pass it to every function.

Do not call this function directly, rather, call omni::graph::exec::unstable::getCurrentTask().

May return nullptr if no task is active on the current thread.

Thread Safety

This method is thread safe.

inline omni::graph::exec::unstable::IExecutor *getCurrentExecutor() noexcept

Access the executor currently executing on the current thread.

Useful when needing to spawn extra work within the scope of the graph.

Do not call this function directly, rather, call omni::graph::exec::unstable::getCurrentExecutor().

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

May return nullptr if an executor is not executing on the curren thread. Note, nullptr may be returned even if omni::graph::exec::unstable::getCurrentTask() returns a valid value.

Thread Safety

This method is thread safe.

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 Status executeGraph_abi(IGraph *graph, IExecutionContext *context) noexcept = 0

Executes the given omni::graph::exec::unstable::IGraph on the current thread.

Do not call this function directly, rather, call omni::graph::exec::unstable::IExecutionContext::execute().

From an ABI point-of-view, the purpose of this method is to handle the special case of the top-level omni::graph::exec::unstable::INodeGraphDef being contained by omni::graph::exec::unstable::IGraph rather than pointed to by a node in another omni::graph::exec::unstable::INodeGraphDef. Meaningful values are set for the threads current task and executor (see omni::graph::exec::unstable::getCurrentTask() and omni::graph::exec::unstable::getCurrentExecutor()).

For further details on the meaning of the returned value, see Error Handling .

Thread Safety

This method is thread safe.

virtual Status execute_abi(ExecutionTask *task, IExecutor *executor) noexcept = 0

Executes the given task on the current thread.

Do not call this function directly, rather, call omni::graph::exec::unstable::ExecutionTask::execute().

This method executes the definition of the node pointed to by the given task. Importantly, this method sets thread local data to track the currently running task and executor (see omni::graph::exec::unstable::getCurrentTask() and omni::graph::exec::unstable::getCurrentExecutor()).

Both the given task and executor must not be nullptr.

The node in the given task will be executed and its status set. This status can be retrieved with omni::graph::exec::unstable::ExecutionTask::getExecutionStatus().

Once the node has been executed, omni::graph::exec::unstable::IExecutor::continueExecute() is called and its status returned. The returned status may not be the same as the status set on the task that was executed.

For further details on the meaning of the returned value, see Error Handling .

It is not an error if the given node does not have an attached definition.

Thread Safety

This method is thread safe.

virtual ExecutionTask *getCurrentTask_abi() noexcept = 0

Access the task currently executing on the current thread.

This is useful when needing to access execution context state without having to pass it to every function.

Do not call this function directly, rather, call omni::graph::exec::unstable::getCurrentTask().

May return nullptr if no task is active on the current thread.

Thread Safety

This method is thread safe.

virtual IExecutor *getCurrentExecutor_abi() noexcept = 0

Access the executor currently executing on the current thread.

Useful when needing to spawn extra work within the scope of the graph.

Do not call this function directly, rather, call omni::graph::exec::unstable::getCurrentExecutor().

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

May return nullptr if an executor is not executing on the curren thread. Note, nullptr may be returned even if omni::graph::exec::unstable::getCurrentTask() returns a valid value.

Thread Safety

This method is thread safe.

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.