ISettings keys

Tasking supports a rich array of carb::settings::ISettings keys to aid in debugging issues and tuning performance. Some settings are marked as “Dynamic” which means the system will detect when they change at runtime and adjust accordingly.

Note

All of the keys in the table below are prefixed with /plugins/carb.tasking.plugin/

Tasking Settings

Name	Type	Default	Dynamic	Description
fiberCount	int	4095	No	The maximum number of fibers that may exist.
threadCount	int	0	No	The number of task threads. A value of “0” means to create one thread per logical CPU (i.e. the amount returned from carb::thread::hardware_concurrency())
threadAffinity	int array	empty	No	Must have length equal to threadCount. Each entry specifies a zero-based CPU identifier to assign a thread to.
stuckCheckSeconds	int	1	Yes	The number of seconds that must elapse before carb.tasking checks to see if it is possibly stuck. A value of 0 disables checking. “Stuck” is defined as having tasks ready to resume but all task threads are still busy with the same tasks before the start of the “stuck” checking start period. Changing this setting dynamically restarts the check period with the new value.
debugWaitingTasks	bool	false	No	Creates a thread for each waiting task so that they are visible in the debugger, particularly Visual Studio’s Parallel Stacks view. Note: This can create hundreds of threads and may cause reduced performance. See the debugging guide.
debugTaskBacktrace	bool	See Description	Yes	Defaults to on (true) for debug builds and off (false) for release builds. Captures a callstack for each call to carb::tasking::ITasking::addTask() variants. When executing the task, the TaskBundle::tryExecute callstack frame will have a local variable DebugTaskCreationCallstack that will have the task creation callstack. When a task is about to enter a waiting state, the callstack is captured and stored so that it is visible in the debugger. Similarly, carb::tasking::ITasking::createCounter and carb::tasking::ITasking::createCounterWithTarget will capture the creation callstack and save it as a local variable DebugCounterCreationCallstack in the carb::tasking::Counter::wait callstack frame. When carb.tasking is unloaded, the creation callstack of any leaked carb::tasking::Counter object is logged as a warning. See the debugging guide. When changed dynamically, only tasks that start after the setting change are affected.
resetFiberStack	bool	true	Yes	A fiber stack reserves the same memory as a thread stack, but memory is only committed (consumed from physical memory) as necessary. When the fiber finishes, stack memory is reclaimed if this setting is true, which can take some time. A setting of true prefers saving memory, whereas a setting of false prefers faster execution. When changed dynamically, only tasks that finish after the setting change are affected.
recordTaskCounts	bool	true	Yes	Maintains a database of task counts by function for debugging purposes, though this does have a performance cost.
debugLocks	bool	false	No	Enables debugging that will assert and log errors if a task enters a sleeping or waiting state while having a SRWLOCK or CRITICAL_SECTION locked (i.e. std::mutex, std::recursive_mutex, etc.). Windows-only. See the debugging guide.
useOmniJob	bool	false	No	Directs carb.tasking.plugin to use omni::experimental::job::IJob and IJobWorker interfaces (such as provided by omni.experimental.job.plugin) for its thread-pool if available. Your application must ensure that those interfaces are available prior to acquiring ITasking. If these interfaces are used, the threadCount setting and TaskingDesc::threadCount member are ignored, instead using the number of workers reported by IJobWorker. NOTE: Changing the number of workers once `ITasking` is acquired is Undefined Behavior.
suppressTaskException	bool	true	Yes	If true, carb.tasking.plugin will catch any unhandled exceptions that tasks throw and will log an error message, but the application is allowed to continue. If false, the unhandled exception is not caught and can proceed to call std::terminate (or interrupt the debugger at the point thrown).
debugAlwaysContextSwitch	bool	false	No	Read at carb.tasking.plugin startup only. If true, any interaction with the scheduler that could result in a context switch will result in a context switch to a different thread (excepting pinned tasks and applyRange). This is a debugging mode intended to help reveal issues at runtime where context-switch-unsafe behavior is performed (such as holding mutex locks during a context switch).