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.