Blender  V3.3
BLI_task.h
Go to the documentation of this file.
1 /* SPDX-License-Identifier: GPL-2.0-or-later */
2 
3 /* Use a define instead of `#pragma once` because of `bmesh_iterators_inline.h` */
4 #ifndef __BLI_TASK_H__
5 #define __BLI_TASK_H__
6 
7 #include <string.h> /* for memset() */
8 
9 struct ListBase;
10 
15 #include "BLI_threads.h"
16 #include "BLI_utildefines.h"
17 
18 #ifdef __cplusplus
19 extern "C" {
20 #endif
21 
22 struct BLI_mempool;
23 
24 /* -------------------------------------------------------------------- */
34 void BLI_task_scheduler_init(void);
35 void BLI_task_scheduler_exit(void);
37 
40 /* -------------------------------------------------------------------- */
55 typedef enum eTaskPriority {
59 
60 typedef struct TaskPool TaskPool;
61 typedef void (*TaskRunFunction)(TaskPool *__restrict pool, void *taskdata);
62 typedef void (*TaskFreeFunction)(TaskPool *__restrict pool, void *taskdata);
63 
69 
75 
81 
88 
93 
95 
97  TaskRunFunction run,
98  void *taskdata,
99  bool free_taskdata,
100  TaskFreeFunction freedata);
101 
110 
117 
122 
127 
130 /* -------------------------------------------------------------------- */
137 typedef struct TaskParallelTLS {
144 
145 typedef void (*TaskParallelRangeFunc)(void *__restrict userdata,
146  int iter,
147  const TaskParallelTLS *__restrict tls);
148 
149 typedef void (*TaskParallelInitFunc)(const void *__restrict userdata, void *__restrict chunk);
150 
151 typedef void (*TaskParallelReduceFunc)(const void *__restrict userdata,
152  void *__restrict chunk_join,
153  void *__restrict chunk);
154 
155 typedef void (*TaskParallelFreeFunc)(const void *__restrict userdata, void *__restrict chunk);
156 
157 typedef struct TaskParallelSettings {
158  /* Whether caller allows to do threading of the particular range.
159  * Usually set by some equation, which forces threading off when threading
160  * overhead becomes higher than speed benefit.
161  * BLI_task_parallel_range() by itself will always use threading when range
162  * is higher than a chunk size. As in, threading will always be performed.
163  */
165  /* Each instance of looping chunks will get a copy of this data
166  * (similar to OpenMP's firstprivate).
167  */
168  void *userdata_chunk; /* Pointer to actual data. */
169  size_t userdata_chunk_size; /* Size of that data. */
170  /* Function called from calling thread once whole range have been
171  * processed.
172  */
173  /* Function called to initialize user data chunk,
174  * typically to allocate data, freed by `func_free`.
175  */
177  /* Function called to join user data chunk into another, to reduce
178  * the result to the original userdata_chunk memory.
179  * The reduce functions should have no side effects, so that they
180  * can be run on any thread. */
182  /* Function called to free data created by TaskParallelRangeFunc. */
184  /* Minimum allowed number of range iterators to be handled by a single
185  * thread. This allows to achieve following:
186  * - Reduce amount of threading overhead.
187  * - Partially occupy thread pool with ranges which are computationally
188  * expensive, but which are smaller than amount of available threads.
189  * For example, it's possible to multi-thread [0 .. 64] range into 4
190  * thread which will be doing 16 iterators each.
191  * This is a preferred way to tell scheduler when to start threading than
192  * having a global use_threading switch based on just range size.
193  */
196 
198 
199 void BLI_task_parallel_range(int start,
200  int stop,
201  void *userdata,
203  const TaskParallelSettings *settings);
204 
209  /* Maximum amount of items to acquire at once. */
211  /* Next item to be acquired. */
212  void *next_item;
213  /* Index of the next item to be acquired. */
215  /* Indicates that end of iteration has been reached. */
217  /* Helper lock to protect access to this data in iterator getter callback,
218  * can be ignored (if the callback implements its own protection system, using atomics e.g.).
219  * Will be NULL when iterator is actually processed in a single thread. */
222 
223 typedef void (*TaskParallelIteratorIterFunc)(void *__restrict userdata,
224  const TaskParallelTLS *__restrict tls,
225  void **r_next_item,
226  int *r_next_index,
227  bool *r_do_abort);
228 
229 typedef void (*TaskParallelIteratorFunc)(void *__restrict userdata,
230  void *item,
231  int index,
232  const TaskParallelTLS *__restrict tls);
233 
248 void BLI_task_parallel_iterator(void *userdata,
250  void *init_item,
251  int init_index,
252  int items_num,
254  const TaskParallelSettings *settings);
255 
267 void BLI_task_parallel_listbase(struct ListBase *listbase,
268  void *userdata,
270  const TaskParallelSettings *settings);
271 
272 typedef struct MempoolIterData MempoolIterData;
273 
274 typedef void (*TaskParallelMempoolFunc)(void *userdata,
275  MempoolIterData *iter,
276  const TaskParallelTLS *__restrict tls);
287 void BLI_task_parallel_mempool(struct BLI_mempool *mempool,
288  void *userdata,
290  const TaskParallelSettings *settings);
291 
294 {
295  memset(settings, 0, sizeof(*settings));
296  settings->use_threading = true;
297  /* Use default heuristic to define actual chunk size. */
298  settings->min_iter_per_thread = 0;
299 }
300 
302 {
303  memset(settings, 0, sizeof(*settings));
304  settings->use_threading = true;
305 }
306 
312 
315 /* -------------------------------------------------------------------- */
384 struct TaskGraph;
385 struct TaskNode;
386 
387 typedef void (*TaskGraphNodeRunFunction)(void *__restrict task_data);
389 
390 struct TaskGraph *BLI_task_graph_create(void);
391 void BLI_task_graph_work_and_wait(struct TaskGraph *task_graph);
392 void BLI_task_graph_free(struct TaskGraph *task_graph);
393 struct TaskNode *BLI_task_graph_node_create(struct TaskGraph *task_graph,
395  void *user_data,
397 bool BLI_task_graph_node_push_work(struct TaskNode *task_node);
398 void BLI_task_graph_edge_create(struct TaskNode *from_node, struct TaskNode *to_node);
399 
402 /* -------------------------------------------------------------------- */
432 void BLI_task_isolate(void (*func)(void *userdata), void *userdata);
433 
436 #ifdef __cplusplus
437 }
438 #endif
439 
440 #endif
#define BLI_INLINE
void BLI_task_scheduler_init(void)
int BLI_task_scheduler_num_threads(void)
eTaskPriority
Definition: BLI_task.h:55
@ TASK_PRIORITY_LOW
Definition: BLI_task.h:56
@ TASK_PRIORITY_HIGH
Definition: BLI_task.h:57
void(* TaskParallelReduceFunc)(const void *__restrict userdata, void *__restrict chunk_join, void *__restrict chunk)
Definition: BLI_task.h:151
void(* TaskGraphNodeFreeFunction)(void *task_data)
Definition: BLI_task.h:388
void BLI_task_graph_edge_create(struct TaskNode *from_node, struct TaskNode *to_node)
Definition: task_graph.cc:139
struct MempoolIterData MempoolIterData
Definition: BLI_task.h:272
void BLI_task_isolate(void(*func)(void *userdata), void *userdata)
void * BLI_task_pool_user_data(TaskPool *pool)
Definition: task_pool.cc:525
struct TaskGraph * BLI_task_graph_create(void)
Definition: task_graph.cc:98
bool BLI_task_pool_current_canceled(TaskPool *pool)
Definition: task_pool.cc:510
void BLI_task_pool_work_and_wait(TaskPool *pool)
Definition: task_pool.cc:480
struct TaskParallelTLS TaskParallelTLS
void BLI_task_pool_cancel(TaskPool *pool)
Definition: task_pool.cc:495
void(* TaskParallelIteratorIterFunc)(void *__restrict userdata, const TaskParallelTLS *__restrict tls, void **r_next_item, int *r_next_index, bool *r_do_abort)
Definition: BLI_task.h:223
void BLI_task_scheduler_exit(void)
bool BLI_task_graph_node_push_work(struct TaskNode *task_node)
Definition: task_graph.cc:127
TaskPool * BLI_task_pool_create_background_serial(void *userdata, eTaskPriority priority)
Definition: task_pool.cc:435
void(* TaskParallelInitFunc)(const void *__restrict userdata, void *__restrict chunk)
Definition: BLI_task.h:149
ThreadMutex * BLI_task_pool_user_mutex(TaskPool *pool)
Definition: task_pool.cc:530
void BLI_task_parallel_range(int start, int stop, void *userdata, TaskParallelRangeFunc func, const TaskParallelSettings *settings)
Definition: task_range.cc:94
void(* TaskParallelRangeFunc)(void *__restrict userdata, int iter, const TaskParallelTLS *__restrict tls)
Definition: BLI_task.h:145
TaskPool * BLI_task_pool_create(void *userdata, eTaskPriority priority)
Definition: task_pool.cc:390
struct TaskNode * BLI_task_graph_node_create(struct TaskGraph *task_graph, TaskGraphNodeRunFunction run, void *user_data, TaskGraphNodeFreeFunction free_func)
Definition: task_graph.cc:117
void BLI_task_graph_free(struct TaskGraph *task_graph)
Definition: task_graph.cc:103
int BLI_task_parallel_thread_id(const TaskParallelTLS *tls)
TaskPool * BLI_task_pool_create_background(void *userdata, eTaskPriority priority)
Definition: task_pool.cc:407
BLI_INLINE void BLI_parallel_range_settings_defaults(TaskParallelSettings *settings)
Definition: BLI_task.h:293
void BLI_task_parallel_iterator(void *userdata, TaskParallelIteratorIterFunc iter_func, void *init_item, int init_index, int items_num, TaskParallelIteratorFunc func, const TaskParallelSettings *settings)
void BLI_task_parallel_mempool(struct BLI_mempool *mempool, void *userdata, TaskParallelMempoolFunc func, const TaskParallelSettings *settings)
TaskPool * BLI_task_pool_create_suspended(void *userdata, eTaskPriority priority)
Definition: task_pool.cc:417
void(* TaskParallelIteratorFunc)(void *__restrict userdata, void *item, int index, const TaskParallelTLS *__restrict tls)
Definition: BLI_task.h:229
struct TaskParallelIteratorStateShared TaskParallelIteratorStateShared
BLI_INLINE void BLI_parallel_mempool_settings_defaults(TaskParallelSettings *settings)
Definition: BLI_task.h:301
void(* TaskGraphNodeRunFunction)(void *__restrict task_data)
Definition: BLI_task.h:387
void BLI_task_parallel_listbase(struct ListBase *listbase, void *userdata, TaskParallelIteratorFunc func, const TaskParallelSettings *settings)
TaskPool * BLI_task_pool_create_no_threads(void *userdata)
Definition: task_pool.cc:426
void(* TaskFreeFunction)(TaskPool *__restrict pool, void *taskdata)
Definition: BLI_task.h:62
void(* TaskParallelMempoolFunc)(void *userdata, MempoolIterData *iter, const TaskParallelTLS *__restrict tls)
Definition: BLI_task.h:274
void BLI_task_graph_work_and_wait(struct TaskGraph *task_graph)
Definition: task_graph.cc:108
void BLI_task_pool_free(TaskPool *pool)
Definition: task_pool.cc:440
void(* TaskParallelFreeFunc)(const void *__restrict userdata, void *__restrict chunk)
Definition: BLI_task.h:155
struct TaskParallelSettings TaskParallelSettings
void BLI_task_pool_push(TaskPool *pool, TaskRunFunction run, void *taskdata, bool free_taskdata, TaskFreeFunction freedata)
Definition: task_pool.cc:459
pthread_spinlock_t SpinLock
Definition: BLI_threads.h:110
pthread_mutex_t ThreadMutex
Definition: BLI_threads.h:82
void * user_data
SyclQueue void void size_t num_bytes void
static PyObject * free_func(PyObject *, PyObject *value)
Definition: python.cpp:220
void * task_data
Definition: task_graph.cc:43
TaskParallelReduceFunc func_reduce
Definition: BLI_task.h:181
TaskParallelFreeFunc func_free
Definition: BLI_task.h:183
TaskParallelInitFunc func_init
Definition: BLI_task.h:176
size_t userdata_chunk_size
Definition: BLI_task.h:169
void * userdata_chunk
Definition: BLI_task.h:142
void * userdata
Definition: task_pool.cc:146
function< void(void)> TaskRunFunction
Definition: task.h:16