Blender V5.3
task_pool.cc
Go to the documentation of this file.
1/* SPDX-FileCopyrightText: 2023 Blender Authors
2 *
3 * SPDX-License-Identifier: GPL-2.0-or-later */
4
10
11#include <atomic>
12#include <cstdlib>
13#include <memory>
14#include <utility>
15
16#include "MEM_guardedalloc.h"
17
18#include "DNA_listBase.h"
19
20#include "BLI_assert.hh"
21#include "BLI_mempool.hh"
22#include "BLI_task_c.hh"
23#include "BLI_threads.hh"
24#include "BLI_vector.hh"
25
26#ifdef WITH_TBB
27# include <tbb/blocked_range.h>
28# include <tbb/task_arena.h>
29# include <tbb/task_group.h>
30#endif
31
32namespace blender {
33
34struct ThreadSlot;
35
41class Task {
42 public:
45 void *taskdata;
48
57
59 {
60 if (free_taskdata) {
61 if (freedata) {
63 }
64 else {
66 }
67 }
68 }
69
70 /* Move constructor.
71 * For performance, ensure we never copy the task and only move it.
72 * For TBB version 2017 and earlier we apply a workaround to make up for
73 * the lack of move constructor support. */
74 Task(Task &&other)
75 : pool(other.pool),
76 run(other.run),
77 taskdata(other.taskdata),
79 freedata(other.freedata)
80 {
81 other.pool = nullptr;
82 other.run = nullptr;
83 other.taskdata = nullptr;
84 other.free_taskdata = false;
85 other.freedata = nullptr;
86 }
87
88/* TBB has a check in `tbb/include/task_group.h` where `__TBB_CPP11_RVALUE_REF_PRESENT` should
89 * evaluate to true as with the other MSVC build. However, because of the clang compiler
90 * it does not and we attempt to call a deleted constructor in the tbb_task_pool_run function.
91 * This check fixes this issue and keeps our Task constructor valid. */
92#if (defined(WITH_TBB) && TBB_INTERFACE_VERSION_MAJOR < 10) || \
93 (defined(_MSC_VER) && defined(__clang__) && TBB_INTERFACE_VERSION_MAJOR < 12)
94 Task(const Task &other)
95 : pool(other.pool),
96 run(other.run),
97 taskdata(other.taskdata),
99 freedata(other.freedata)
100 {
101 ((Task &)other).pool = nullptr;
102 ((Task &)other).run = nullptr;
103 ((Task &)other).taskdata = nullptr;
104 ((Task &)other).free_taskdata = false;
105 ((Task &)other).freedata = nullptr;
106 }
107#else
108 Task(const Task &other) = delete;
109#endif
110
111 Task &operator=(const Task &other) = delete;
112 Task &operator=(Task &&other) = delete;
113
114 void operator()() const;
115};
116
117/* Execute task. */
119{
120 run(pool, taskdata);
121}
122
123/* TBB Task Group.
124 *
125 * Subclass since there seems to be no other way to set priority. */
126
127#ifdef WITH_TBB
128class TBBTaskGroup : public tbb::task_group {
129 public:
130 TBBTaskGroup(eTaskPriority priority)
131 {
132# if TBB_INTERFACE_VERSION_MAJOR >= 12
133 /* TODO: support priorities in TBB 2021, where they are only available as
134 * part of task arenas, no longer for task groups. Or remove support for
135 * task priorities if they are no longer useful. */
136 UNUSED_VARS(priority);
137# else
138 switch (priority) {
140 my_context.set_priority(tbb::priority_low);
141 break;
143 my_context.set_priority(tbb::priority_normal);
144 break;
145 }
146# endif
147 }
148};
149#endif
150
151/* Task Pool */
152
160
161struct TaskPool {
164
165 void *userdata;
166
167#ifdef WITH_TBB
168 /* TBB task pool. */
169 std::unique_ptr<TBBTaskGroup> tbb_group;
170#endif
171 volatile bool is_suspended = false;
173
174 /* Background task pool. */
175 ListBaseT<ThreadSlot> background_threads;
177
179
182 {
183 this->use_threads = BLI_task_scheduler_num_threads() > 1 && type != TASK_POOL_NO_THREADS;
184
185 /* Background task pool uses regular TBB scheduling if available. Only when
186 * building without TBB or running with -t 1 do we need to ensure these tasks
187 * do not block the main thread. */
188 if (this->type == TASK_POOL_BACKGROUND && this->use_threads) {
189 this->type = TASK_POOL_TBB;
190 }
191
192 switch (this->type) {
193 case TASK_POOL_TBB:
197 this->is_suspended = true;
198 }
199
200#ifdef WITH_TBB
201 if (use_threads) {
202 this->tbb_group = std::make_unique<TBBTaskGroup>(priority);
203 }
204#endif
205 break;
206 }
209 this->background_queue = BLI_thread_queue_init();
210 BLI_threadpool_init(&this->background_threads, this->background_task_run, 1);
211 break;
212 }
213 }
214 }
215
217 {
218 switch (type) {
219 case TASK_POOL_TBB:
222 break;
225 this->background_task_pool_work_and_wait();
226
227 BLI_threadpool_end(&this->background_threads);
228 BLI_thread_queue_free(this->background_queue);
229 break;
230 }
231 }
232 }
233
234 TaskPool(TaskPool &&other) = delete;
235#if 0
236 : type(other.type), use_threads(other.use_threads), userdata(other.userdata)
237 {
238 other.pool = nullptr;
239 other.run = nullptr;
240 other.taskdata = nullptr;
241 other.free_taskdata = false;
242 other.freedata = nullptr;
243 }
244#endif
245
246 TaskPool(const TaskPool &other) = delete;
247
248 TaskPool &operator=(const TaskPool &other) = delete;
249 TaskPool &operator=(TaskPool &&other) = delete;
250
255 void *taskdata,
256 bool free_taskdata,
257 TaskFreeFunction freedata)
258 {
259 switch (this->type) {
260 case TASK_POOL_TBB:
263 this->tbb_task_pool_run({this, run, taskdata, free_taskdata, freedata});
264 break;
267 this->background_task_pool_run({this, run, taskdata, free_taskdata, freedata});
268 break;
269 }
270 }
271
276 {
277 switch (this->type) {
278 case TASK_POOL_TBB:
281 this->tbb_task_pool_work_and_wait();
282 break;
285 this->background_task_pool_work_and_wait();
286 break;
287 }
288 }
289
290 private:
291 /* TBB Task Pool.
292 *
293 * Task pool using the TBB scheduler for tasks. When building without TBB
294 * support or running Blender with -t 1, this reverts to single threaded.
295 *
296 * Tasks may be suspended until in all are created, to make it possible to
297 * initialize data structures and create tasks in a single pass. */
298 void tbb_task_pool_run(Task &&task);
299 void tbb_task_pool_work_and_wait();
300
301 /* Background Task Pool.
302 *
303 * Fallback for running background tasks when building without TBB. */
304 void background_task_pool_run(Task &&task);
305 void background_task_pool_work_and_wait();
306 static void *background_task_run(void *userdata);
307};
308
309void TaskPool::tbb_task_pool_run(Task &&task)
310{
312 if (this->is_suspended) {
313 /* Suspended task that will be executed in work_and_wait(). */
314 this->suspended_tasks.append(std::move(task));
315
316 /* Added as part of original 'use TBB' commit (d8a3f3595af0fb). Unclear whether this is still
317 * needed, tests are passing on linux buildbot, but not sure if any would trigger the issue
318 * addressed by this code. So keeping around for now. */
319#if 0
320# ifdef __GNUC__
321 /* Work around apparent compiler bug where task is not properly copied
322 * to task_mem. This appears unrelated to the use of placement new or
323 * move semantics, happens even writing to a plain C struct. Rather the
324 * call into TBB seems to have some indirect effect. */
325 std::atomic_thread_fence(std::memory_order_release);
326# endif
327#endif
328 }
329#ifdef WITH_TBB
330 else if (this->use_threads) {
331 /* Execute in TBB task group. */
332 this->tbb_group->run(std::move(task));
333 }
334#endif
335 else {
336 /* Execute immediately. */
337 task();
338 }
339}
340
341void TaskPool::tbb_task_pool_work_and_wait()
342{
344 /* Start any suspended task now. */
345 if (!this->suspended_tasks.is_empty()) {
347 this->is_suspended = false;
348
349 for (Task &task : this->suspended_tasks) {
350 this->tbb_task_pool_run(std::move(task));
351 }
352 this->suspended_tasks.clear();
353 }
354
355#ifdef WITH_TBB
356 if (this->use_threads) {
357 /* This is called wait(), but internally it can actually do work. This
358 * matters because we don't want recursive usage of task pools to run
359 * out of threads and get stuck. */
360 this->tbb_group->wait();
361 }
362#endif
363}
364
365void TaskPool::background_task_pool_run(Task &&task)
366{
368
369 Task *task_mem = MEM_new<Task>(__func__, std::move(task));
371 task_mem,
375
378 }
379}
380
381void TaskPool::background_task_pool_work_and_wait()
382{
384
385 /* Signal background thread to stop waiting for new tasks if none are
386 * left, and wait for tasks and thread to finish. */
390}
391
392void *TaskPool::background_task_run(void *userdata)
393{
394 TaskPool *pool = static_cast<TaskPool *>(userdata);
395 while (Task *task = static_cast<Task *>(BLI_thread_queue_pop(pool->background_queue))) {
396 (*task)();
397 MEM_delete(task);
398 }
399 return nullptr;
400}
401
402/* Task Pool public API. */
403
405{
406 return MEM_new<TaskPool>(__func__, TASK_POOL_TBB, priority, userdata);
407}
408
410{
411 /* NOTE: In multi-threaded context, there is no differences with #BLI_task_pool_create(),
412 * but in single-threaded case it is ensured to have at least one worker thread to run on
413 * (i.e. you don't have to call #BLI_task_pool_work_and_wait
414 * on it to be sure it will be processed).
415 *
416 * NOTE: Background pools are non-recursive
417 * (that is, you should not create other background pools in tasks assigned to a background pool,
418 * they could end never being executed, since the 'fallback' background thread is already
419 * busy with parent task in single-threaded context). */
420 return MEM_new<TaskPool>(__func__, TASK_POOL_BACKGROUND, priority, userdata);
421}
422
424{
425 /* NOTE: Similar to #BLI_task_pool_create() but does not schedule any tasks for execution
426 * for until BLI_task_pool_work_and_wait() is called. This helps reducing threading
427 * overhead when pushing huge amount of small initial tasks from the main thread. */
428 return MEM_new<TaskPool>(__func__, TASK_POOL_TBB_SUSPENDED, priority, userdata);
429}
430
432{
433 return MEM_new<TaskPool>(__func__, TASK_POOL_NO_THREADS, TASK_PRIORITY_HIGH, userdata);
434}
435
437{
438 return MEM_new<TaskPool>(__func__, TASK_POOL_BACKGROUND_SERIAL, priority, userdata);
439}
440
442{
443 MEM_delete(pool);
444}
445
447 TaskRunFunction run,
448 void *taskdata,
449 bool free_taskdata,
450 TaskFreeFunction freedata)
451{
452 pool->task_push(run, taskdata, free_taskdata, freedata);
453}
454
456{
457 pool->work_and_wait();
458}
459
461{
462 return pool->userdata;
463}
464
465} // namespace blender
These structs are the foundation for all linked lists in the library system.
Read Blender memory allocation and freeing.
#define UNUSED_VARS(...)
#define BLI_assert(a)
#define ELEM(...)
void * taskdata
Definition task_pool.cc:45
Task(Task &&other)
Definition task_pool.cc:74
Task & operator=(const Task &other)=delete
Task(TaskPool *pool, TaskRunFunction run, void *taskdata, bool free_taskdata, TaskFreeFunction freedata)
Definition task_pool.cc:49
void operator()() const
Definition task_pool.cc:118
TaskRunFunction run
Definition task_pool.cc:44
bool free_taskdata
Definition task_pool.cc:46
TaskPool * pool
Definition task_pool.cc:43
Task & operator=(Task &&other)=delete
TaskFreeFunction freedata
Definition task_pool.cc:47
Task(const Task &other)=delete
BMesh Iterators.
void BLI_thread_queue_nowait(ThreadQueue *queue)
Definition threads.cc:856
int BLI_available_threads(ListBaseT< ThreadSlot > *threadbase)
Definition threads.cc:148
@ BLI_THREAD_QUEUE_WORK_PRIORITY_HIGH
@ BLI_THREAD_QUEUE_WORK_PRIORITY_NORMAL
@ TASK_PRIORITY_HIGH
Definition BLI_task_c.hh:61
@ TASK_PRIORITY_LOW
Definition BLI_task_c.hh:60
TaskPool * BLI_task_pool_create_suspended(void *userdata, eTaskPriority priority)
Definition task_pool.cc:423
int BLI_task_scheduler_num_threads()
void BLI_thread_queue_wait_finish(ThreadQueue *queue)
Definition threads.cc:867
void BLI_threadpool_insert(ListBaseT< ThreadSlot > *threadbase, void *callerdata)
Definition threads.cc:189
void BLI_threadpool_end(ListBaseT< ThreadSlot > *threadbase)
Definition threads.cc:239
TaskPool * BLI_task_pool_create_no_threads(void *userdata)
Definition task_pool.cc:431
void MEM_delete_void(void *vmemh)
void BLI_task_pool_work_and_wait(TaskPool *pool)
Definition task_pool.cc:455
void * BLI_task_pool_user_data(TaskPool *pool)
Definition task_pool.cc:460
TaskPool * BLI_task_pool_create_background_serial(void *userdata, eTaskPriority priority)
Definition task_pool.cc:436
@ TASK_POOL_NO_THREADS
Definition task_pool.cc:156
@ TASK_POOL_TBB_SUSPENDED
Definition task_pool.cc:155
@ TASK_POOL_TBB
Definition task_pool.cc:154
@ TASK_POOL_BACKGROUND_SERIAL
Definition task_pool.cc:158
@ TASK_POOL_BACKGROUND
Definition task_pool.cc:157
void(*) TaskRunFunction(TaskPool *__restrict pool, void *taskdata)
Definition BLI_task_c.hh:65
void BLI_thread_queue_free(ThreadQueue *queue)
Definition threads.cc:638
ThreadQueue * BLI_thread_queue_init()
Definition threads.cc:627
void * BLI_thread_queue_pop(ThreadQueue *queue)
Definition threads.cc:717
void BLI_task_pool_free(TaskPool *pool)
Definition task_pool.cc:441
void(*) TaskFreeFunction(TaskPool *__restrict pool, void *taskdata)
Definition BLI_task_c.hh:66
TaskPool * BLI_task_pool_create(void *userdata, eTaskPriority priority)
Definition task_pool.cc:404
uint64_t BLI_thread_queue_push(ThreadQueue *queue, void *work, ThreadQueueWorkPriority priority)
Definition threads.cc:648
void BLI_task_pool_push(TaskPool *pool, TaskRunFunction run, void *taskdata, bool free_taskdata, TaskFreeFunction freedata)
Definition task_pool.cc:446
void BLI_threadpool_init(ListBaseT< ThreadSlot > *threadbase, void *(*do_thread)(void *), int tot)
Definition threads.cc:123
void BLI_threadpool_clear(ListBaseT< ThreadSlot > *threadbase)
Definition threads.cc:228
TaskPool * BLI_task_pool_create_background(void *userdata, eTaskPriority priority)
Definition task_pool.cc:409
volatile bool is_suspended
Definition task_pool.cc:171
TaskPool(const TaskPoolType type, const eTaskPriority priority, void *userdata)
Definition task_pool.cc:180
TaskPool(TaskPool &&other)=delete
void task_push(TaskRunFunction run, void *taskdata, bool free_taskdata, TaskFreeFunction freedata)
Definition task_pool.cc:254
TaskPoolType type
Definition task_pool.cc:162
eTaskPriority priority
Definition task_pool.cc:178
ListBaseT< ThreadSlot > background_threads
Definition task_pool.cc:175
TaskPool(const TaskPool &other)=delete
Vector< Task > suspended_tasks
Definition task_pool.cc:172
ThreadQueue * background_queue
Definition task_pool.cc:176
TaskPool & operator=(TaskPool &&other)=delete
TaskPool & operator=(const TaskPool &other)=delete