Blender V5.3
BLI_task_c.hh File Reference
#include <string.h>
#include "BLI_threads.hh"
#include "BLI_utildefines.hh"

Go to the source code of this file.

Classes

struct  blender::TaskParallelTLS
struct  blender::TaskParallelSettings

Namespaces

namespace  blender
 BMesh Iterators.

Functions

Task Scheduler

Central scheduler that holds running threads ready to execute tasks. A single queue holds the task from all pools.

Initialize/exit must be called before/after any task pools are created/freed, and must be called from the main threads. All other scheduler and pool functions are thread-safe.

void blender::BLI_task_scheduler_init (bool use_flush_denormals_to_zero=true)
void blender::BLI_task_scheduler_exit ()
int blender::BLI_task_scheduler_num_threads ()
Task Isolation

Task isolation helps avoid unexpected task scheduling decisions that can lead to bugs if wrong assumptions were made. Typically that happens when doing "nested threading", i.e. one thread schedules a bunch of main-tasks and those spawn new sub-tasks.

What can happen is that when a main-task waits for its sub-tasks to complete on other threads, another main-task is scheduled within the already running main-task. Generally, this is good, because it leads to better performance. However, sometimes code (often unintentionally) makes the assumption that at most one main-task runs on a thread at a time.

The bugs often show themselves in two ways:

  • Deadlock, when a main-task holds a mutex while waiting for its sub-tasks to complete.
  • Data corruption, when a main-task makes wrong assumptions about a thread-local variable.

Task isolation can avoid these bugs by making sure that a main-task does not start executing another main-task while waiting for its sub-tasks. More precisely, a function that runs in an isolated region is only allowed to run sub-tasks that were spawned in the same isolated region.

Unfortunately, incorrect use of task isolation can lead to deadlocks itself. This can happen when threading primitives are used that separate spawning tasks from executing them. The problem occurs when a task is spawned in one isolated region while the tasks are waited for in another isolated region. In this setup, the thread that is waiting for the spawned tasks to complete cannot run the tasks itself. On a single thread, that causes a deadlock already. When there are multiple threads, another thread will typically run the task and avoid the deadlock. However, if this situation happens on all threads at the same time, all threads will deadlock. This happened in #88598.

void blender::BLI_task_isolate (void(*func)(void *userdata), void *userdata)

Task Pool

Pool of tasks that will be executed by the central task scheduler. For each pool, we can wait for all tasks to be done.

Running tasks may spawn new tasks.

Pools may be nested, i.e. a thread running a task can create another task pool with smaller tasks. When other threads are busy they will continue working on their own tasks, if not they will join in, no new threads will be launched.

Note: task cancellation used to be exposed too, but at least with TBB it has several non-intuitive repercussions (#152467, #143662); avoid re-adding it again.

enum  blender::eTaskPriority { blender::TASK_PRIORITY_LOW , blender::TASK_PRIORITY_HIGH }
typedef void(*) blender::TaskRunFunction(TaskPool *__restrict pool, void *taskdata)
typedef void(*) blender::TaskFreeFunction(TaskPool *__restrict pool, void *taskdata)
TaskPool * blender::BLI_task_pool_create (void *userdata, eTaskPriority priority)
TaskPool * blender::BLI_task_pool_create_background (void *userdata, eTaskPriority priority)
TaskPool * blender::BLI_task_pool_create_background_serial (void *userdata, eTaskPriority priority)
TaskPool * blender::BLI_task_pool_create_suspended (void *userdata, eTaskPriority priority)
TaskPool * blender::BLI_task_pool_create_no_threads (void *userdata)
void blender::BLI_task_pool_free (TaskPool *pool)
void blender::BLI_task_pool_push (TaskPool *pool, TaskRunFunction run, void *taskdata, bool free_taskdata, TaskFreeFunction freedata)
void blender::BLI_task_pool_work_and_wait (TaskPool *pool)
void * blender::BLI_task_pool_user_data (TaskPool *pool)

Parallel for Routines

typedef void(*) blender::TaskParallelRangeFunc(void *__restrict userdata, int iter, const TaskParallelTLS *__restrict tls)
typedef void(*) blender::TaskParallelInitFunc(const void *__restrict userdata, void *__restrict chunk)
typedef void(*) blender::TaskParallelReduceFunc(const void *__restrict userdata, void *__restrict chunk_join, void *__restrict chunk)
typedef void(*) blender::TaskParallelFreeFunc(const void *__restrict userdata, void *__restrict chunk)
typedef void(*) blender::TaskParallelMempoolFunc(void *userdata, MempoolIterData *iter, const TaskParallelTLS *__restrict tls)
BLI_INLINE void blender::BLI_parallel_range_settings_defaults (TaskParallelSettings *settings)
void blender::BLI_task_parallel_range (int start, int stop, void *userdata, TaskParallelRangeFunc func, const TaskParallelSettings *settings)
void blender::BLI_task_parallel_mempool (struct BLI_mempool *mempool, void *userdata, TaskParallelMempoolFunc func, const TaskParallelSettings *settings)
BLI_INLINE void blender::BLI_parallel_mempool_settings_defaults (TaskParallelSettings *settings)
int blender::BLI_task_parallel_thread_id (const TaskParallelTLS *tls)

Task Graph Scheduling

Task Graphs can be used to create a forest of directional trees and schedule work to any tree. The nodes in the graph can be run in separate threads.

+---- [root] ----+
| |
v v
[node_1] +---- [node_2] ----+
| |
v v
[node_3] [node_4]
TaskGraph *task_graph = BLI_task_graph_create();
TaskNode *root = BLI_task_graph_node_create(task_graph, root_exec, NULL, NULL);
TaskNode *node_1 = BLI_task_graph_node_create(task_graph, node_exec, NULL, NULL);
TaskNode *node_2 = BLI_task_graph_node_create(task_graph, node_exec, NULL, NULL);
TaskNode *node_3 = BLI_task_graph_node_create(task_graph, node_exec, NULL, NULL);
TaskNode *node_4 = BLI_task_graph_node_create(task_graph, node_exec, NULL, NULL);
BLI_task_graph_edge_create(root, node_1);
BLI_task_graph_edge_create(root, node_2);
BLI_task_graph_edge_create(node_2, node_3);
BLI_task_graph_edge_create(node_2, node_4);

Any node can be triggered to start a chain of tasks. Normally you would trigger a root node but it is supported to start the chain of tasks anywhere in the forest or tree. When a node completes, the execution flow is forwarded via the created edges. When a child node has multiple parents the child node will be triggered once for each parent.

BLI_task_graph_node_push_work(root);

In this example After root is finished, node_1 and node_2 will be started. Only after node_2 is finished node_3 and node_4 will be started.

After scheduling work we need to wait until all the tasks have been finished.

BLI_task_graph_work_and_wait();

When finished you can clean up all the resources by freeing the task_graph. Nodes are owned by the graph and are freed task_data will only be freed if a free_func was given.

BLI_task_graph_free(task_graph);

Work can enter a tree on any node. Normally this would be the root_node. A task_graph can be reused, but the caller needs to make sure the task_data is reset.

Task-Data

Typically you want give a task data to work on. Task data can be shared with other nodes, but be careful not to free the data multiple times. Task data is freed when calling #BLI_task_graph_free.

MyData *task_data = MEM_new_zeroed<MyData>(__func__);
TaskNode *root = BLI_task_graph_node_create(task_graph, root_exec, task_data, MEM_delete);
TaskNode *node_1 = BLI_task_graph_node_create(task_graph, node_exec, task_data, NULL);
TaskNode *node_2 = BLI_task_graph_node_create(task_graph, node_exec, task_data, NULL);
TaskNode *node_3 = BLI_task_graph_node_create(task_graph, node_exec, task_data, NULL);
TaskNode *node_4 = BLI_task_graph_node_create(task_graph, node_exec, task_data, NULL);
void * MEM_new_zeroed(size_t len, const char *str)
Definition mallocn.cc:114
typedef void(*) blender::TaskGraphNodeRunFunction(void *__restrict task_data)
typedef void(*) blender::TaskGraphNodeFreeFunction(void *task_data)
struct TaskGraph * blender::BLI_task_graph_create ()
void blender::BLI_task_graph_work_and_wait (struct TaskGraph *task_graph)
void blender::BLI_task_graph_free (struct TaskGraph *task_graph)
struct TaskNode * blender::BLI_task_graph_node_create (struct TaskGraph *task_graph, TaskGraphNodeRunFunction run, void *user_data, TaskGraphNodeFreeFunction free_func)
bool blender::BLI_task_graph_node_push_work (struct TaskNode *task_node)
void blender::BLI_task_graph_edge_create (struct TaskNode *from_node, struct TaskNode *to_node)