carb::tasking::TaskDebugInfo

Defined in carb/tasking/TaskingTypes.h

struct TaskDebugInfo

Defines debug information about a task retrieved by ITasking::getTaskDebugInfo() or ITasking::walkTaskDebugInfo().

Note

This information is intended for debug only and should not affect application state or decisions in the application.

Warning

Since carb.tasking is an inherently multi-threaded API, the values presented as task debug information may have changed in a worker thread in the short amount of time between when they were generated and when they were read by the application. As such, the debug information was true at a previous point in time and should not be considered necessarily up-to-date.

Public Members

size_t sizeOf = {sizeof(TaskDebugInfo)}

Size of this struct, used for versioning.

TaskContext context = {}

The TaskContext handle for the task.

TaskDebugState state = {}

The state of the task.

OnTaskFn task = {}

The task function for this task that was submitted to ITasking::addTask() (or variant function), if known. May be nullptr if the task has finished or was canceled.

void *taskArg = {}

The task argument for this task that was submitted to ITasking::addTask() (or variant function), if known. May be nullptr if the task has finished or was canceled.

size_t numCreationFrames = {0}

Input: the maximum number of frames that can be stored in the memory pointed to by the creationCallstack member. Output: the number of frames that were stored in the memory pointed to by the creationCallstack member.

void **creationCallstack = {nullptr}

The callstack that called ITasking::addTask() (or variant function). The callstack is only available if carb.tasking is configured to capture callstacks with setting /plugins/carb.tasking.plugin/debugTaskBacktrace.

Note

If this value is desired, prior to calling ITasking::getTaskDebugInfo() set this member to a buffer that will be filled by the ITasking::getTaskDebugInfo() function. Set numCreationFrames to the number of frames that can be contained in the buffer. After calling ITasking::getTaskDebugInfo(), this member will contain the available creation callstack frames and numCreationFrames will be set to the number of frames that could be written.

size_t numWaitingFrames = {0}

Input: the maximum number of frames that can be stored in the memory pointed to by the waitingCallstack member. Output: the number of frames that were stored in the memory pointed to by the waitingCallstack member.

void **waitingCallstack = {nullptr}

The callstack of the task when waiting. This is only captured if carb.tasking is configured to capture callstacks with setting /plugins/carb.tasking.plugin/debugTaskBacktrace and if state is TaskDebugState::Waiting.

Note

If this value is desired, prior to calling ITasking::getTaskDebugInfo() set this member to a buffer that will be filled by the ITasking::getTaskDebugInfo() function. Set numWaitingFrames to the number of frames that can be contained in the buffer. After calling ITasking::getTaskDebugInfo(), this member will contain the available waiting callstack frames and numWaitingFrames will be set to the number of frames that could be written.

Warning

Capturing this value is somewhat unsafe as debug information is not stored in a way that will impede task execution whatsoever (i.e. with synchronization), therefore information is gathered from a running task without stopping it. As such, reading the waiting callstack may produce bad data and in extremely rare cases cause a crash. If the state changes while gathering info, state may report TaskDebugState::Waiting but numWaitingFrames may be 0 even though some data was written to the buffer pointed to by waitingCallstack.

size_t taskNameSize = {0}

Input: the maximum number of characters that can be stored in the memory pointed to by the taskName member. Output: the number of characters written (including the NUL terminator) to the memory pointed to by the taskName member.

char *taskName = {nullptr}

A optional buffer that will be filled with the task name if provided.

Note

If this value is desired, prior to calling ITasking::getTaskDebugInfo() set this member to a buffer that will be filled by the ITasking::getTaskDebugInfo() function. Set taskNameSize to the number of characters that can be contained in the buffer. After calling ITasking::getTaskDebugInfo(), this member will contain the NUL-terminated task name and taskNameSize will be set to the number of characters that could be written (including the NUL-terminator).