carb::thread::IThreadUtil

struct IThreadUtil

An interface to provide various thread utility operations.

Currently the only defined operation is to run a task in a single common thread regardless of the thread that requests the operation.

Public Members

RelayResult (*runRelayTask)(RelayTaskDesc &desc)

Relays a task to run on an internal worker thread.

Remark

This relays a task to run on an internal worker thread. This worker thread will be guaranteed to continue running (in an efficient sleep state when not running a task) for the entire remaining lifetime of the process. The thread will be terminated during shutdown of the process.

Remark

The intention of this function is to be able to run generic tasks on a worker thread that is guaranteed to live throughout the process’s lifetime. Other similar systems in other plugins have the possibility of being unloaded before the end of the process which would lead to the task worker thread(s) being stopped early. Certain tasks such may require the instantiating thread to survive longer than the lifetime of a dynamic plugin.

Remark

A task function may queue another task when it executes. However, the behavior may differ depending on whether the newly queued task is flagged as being blocking or non-blocking. A recursive blocking task will be executed immediately in the context of the task thread, but will interrupt any other pending tasks that were queued ahead of it. A recursive non-blocking task will always maintain queuing order however. Note that recursive tasks may require extra care to wait for or halt upon module shutdown or unload. In these cases, it is still the caller’s responsibility to ensure all tasks queued by a module are safely and properly stopped before that module is unloaded.

Note

This should only be used in situations where it is absolutely necessary. In cases where performance or more flexibility are needed, other interfaces such as ITasking should be used instead.

Note

If a caller in another module queues a non-blocking task, it is that caller’s responsibility to ensure that task has completed before its module is unloaded. This can be accomplished by queuing a do-nothing blocking task.

Param desc: [inout] The descriptor of the task to be run. This task includes a function to execute and a context value to pass to that function. This descriptor must remain valid for the entire lifetime of the execution of the task function. If the fRelayFlagBlocking flag is used, this call will block until the task completes. In this case, the caller will be responsible for cleaning up any resources used or returned by the task function. If the flag is not used, the task function itself will be responsible for cleaning up any resources before it returns.
Retval RelayResult::eSuccess: if executing the task is successful.
Return: An error code describing how the task relay failed.

Public Static Functions

static inline constexpr carb::InterfaceDesc getInterfaceDesc() noexcept

Returns information about this interface.

Auto-generated by CARB_PLUGIN_INTERFACE() or CARB_PLUGIN_INTERFACE_EX.

Returns: The carb::InterfaceDesc struct with information about this interface.

static inline constexpr carb::InterfaceDesc getLatestInterfaceDesc() noexcept

Returns information about the latest version of this interface.

Auto-generated by CARB_PLUGIN_INTERFACE() or CARB_PLUGIN_INTERFACE_EX.

Returns: The carb::InterfaceDesc struct with information about the latest version of this interface.