Merge branch 'blender2.7'
[blender.git] / source / blender / blenlib / BLI_task.h
1 /*
2  * This program is free software; you can redistribute it and/or
3  * modify it under the terms of the GNU General Public License
4  * as published by the Free Software Foundation; either version 2
5  * of the License, or (at your option) any later version.
6  *
7  * This program is distributed in the hope that it will be useful,
8  * but WITHOUT ANY WARRANTY; without even the implied warranty of
9  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
10  * GNU General Public License for more details.
11  *
12  * You should have received a copy of the GNU General Public License
13  * along with this program; if not, write to the Free Software Foundation,
14  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
15  */
16
17 #ifndef __BLI_TASK_H__
18 #define __BLI_TASK_H__
19
20 #include <string.h>  /* for memset() */
21
22 struct Link;
23 struct ListBase;
24
25 /** \file
26  * \ingroup bli
27  */
28
29 #ifdef __cplusplus
30 extern "C" {
31 #endif
32
33 #include "BLI_threads.h"
34 #include "BLI_utildefines.h"
35
36 struct BLI_mempool;
37
38 /* Task Scheduler
39  *
40  * Central scheduler that holds running threads ready to execute tasks. A single
41  * queue holds the task from all pools.
42  *
43  * Init/exit must be called before/after any task pools are created/freed, and
44  * must be called from the main threads. All other scheduler and pool functions
45  * are thread-safe. */
46
47 typedef struct TaskScheduler TaskScheduler;
48
49 enum {
50         TASK_SCHEDULER_AUTO_THREADS = 0,
51         TASK_SCHEDULER_SINGLE_THREAD = 1,
52 };
53
54 TaskScheduler *BLI_task_scheduler_create(int num_threads);
55 void BLI_task_scheduler_free(TaskScheduler *scheduler);
56
57 int BLI_task_scheduler_num_threads(TaskScheduler *scheduler);
58
59 /* Task Pool
60  *
61  * Pool of tasks that will be executed by the central TaskScheduler. For each
62  * pool, we can wait for all tasks to be done, or cancel them before they are
63  * done.
64  *
65  * Running tasks may spawn new tasks.
66  *
67  * Pools may be nested, i.e. a thread running a task can create another task
68  * pool with smaller tasks. When other threads are busy they will continue
69  * working on their own tasks, if not they will join in, no new threads will
70  * be launched.
71  */
72
73 typedef enum TaskPriority {
74         TASK_PRIORITY_LOW,
75         TASK_PRIORITY_HIGH
76 } TaskPriority;
77
78 typedef struct TaskPool TaskPool;
79 typedef void (*TaskRunFunction)(TaskPool *__restrict pool, void *taskdata, int threadid);
80 typedef void (*TaskFreeFunction)(TaskPool *__restrict pool, void *taskdata, int threadid);
81
82 TaskPool *BLI_task_pool_create(TaskScheduler *scheduler, void *userdata);
83 TaskPool *BLI_task_pool_create_background(TaskScheduler *scheduler, void *userdata);
84 TaskPool *BLI_task_pool_create_suspended(TaskScheduler *scheduler, void *userdata);
85 void BLI_task_pool_free(TaskPool *pool);
86
87 void BLI_task_pool_push_ex(
88         TaskPool *pool, TaskRunFunction run, void *taskdata,
89         bool free_taskdata, TaskFreeFunction freedata, TaskPriority priority);
90 void BLI_task_pool_push(TaskPool *pool, TaskRunFunction run,
91         void *taskdata, bool free_taskdata, TaskPriority priority);
92 void BLI_task_pool_push_from_thread(TaskPool *pool, TaskRunFunction run,
93         void *taskdata, bool free_taskdata, TaskPriority priority, int thread_id);
94
95 /* work and wait until all tasks are done */
96 void BLI_task_pool_work_and_wait(TaskPool *pool);
97 /* work and wait until all tasks are done, then reset to the initial suspended state */
98 void BLI_task_pool_work_wait_and_reset(TaskPool *pool);
99 /* cancel all tasks, keep worker threads running */
100 void BLI_task_pool_cancel(TaskPool *pool);
101
102 /* for worker threads, test if canceled */
103 bool BLI_task_pool_canceled(TaskPool *pool);
104
105 /* optional userdata pointer to pass along to run function */
106 void *BLI_task_pool_userdata(TaskPool *pool);
107
108 /* optional mutex to use from run function */
109 ThreadMutex *BLI_task_pool_user_mutex(TaskPool *pool);
110
111 /* Delayed push, use that to reduce thread overhead by accumulating
112  * all new tasks into local queue first and pushing it to scheduler
113  * from within a single mutex lock.
114  */
115 void BLI_task_pool_delayed_push_begin(TaskPool *pool, int thread_id);
116 void BLI_task_pool_delayed_push_end(TaskPool *pool, int thread_id);
117
118 /* Parallel for routines */
119
120 typedef enum eTaskSchedulingMode {
121         /* Task scheduler will divide overall work into equal chunks, scheduling
122          * even chunks to all worker threads.
123          * Least run time benefit, ideal for cases when each task requires equal
124          * amount of compute power.
125          */
126         TASK_SCHEDULING_STATIC,
127         /* Task scheduler will schedule small amount of work to each worker thread.
128          * Has more run time overhead, but deals much better with cases when each
129          * part of the work requires totally different amount of compute power.
130          */
131         TASK_SCHEDULING_DYNAMIC,
132 } eTaskSchedulingMode;
133
134 /* Per-thread specific data passed to the callback. */
135 typedef struct ParallelRangeTLS {
136         /* Identifier of the thread who this data belongs to. */
137         int thread_id;
138         /* Copy of user-specifier chunk, which is copied from original chunk to all
139          * worker threads. This is similar to OpenMP's firstprivate.
140          */
141         void *userdata_chunk;
142 } ParallelRangeTLS;
143
144 typedef void (*TaskParallelRangeFunc)(void *__restrict userdata,
145                                       const int iter,
146                                       const ParallelRangeTLS *__restrict tls);
147 typedef void (*TaskParallelRangeFuncFinalize)(void *__restrict userdata,
148                                               void *__restrict userdata_chunk);
149
150 typedef struct ParallelRangeSettings {
151         /* Whether caller allows to do threading of the particular range.
152          * Usually set by some equation, which forces threading off when threading
153          * overhead becomes higher than speed benefit.
154          * BLI_task_parallel_range() by itself will always use threading when range
155          * is higher than a chunk size. As in, threading will always be performed.
156          */
157         bool use_threading;
158         /* Scheduling mode to use for this parallel range invocation. */
159         eTaskSchedulingMode scheduling_mode;
160         /* Each instance of looping chunks will get a copy of this data
161          * (similar to OpenMP's firstprivate).
162          */
163         void *userdata_chunk;        /* Pointer to actual data. */
164         size_t userdata_chunk_size;  /* Size of that data.  */
165         /* Function called from calling thread once whole range have been
166          * processed.
167          */
168         TaskParallelRangeFuncFinalize func_finalize;
169         /* Minimum allowed number of range iterators to be handled by a single
170          * thread. This allows to achieve following:
171          * - Reduce amount of threading overhead.
172          * - Partially occupy thread pool with ranges which are computationally
173          *   expensive, but which are smaller than amount of available threads.
174          *   For example, it's possible to multi-thread [0 .. 64] range into 4
175          *   thread which will be doing 16 iterators each.
176          * This is a preferred way to tell scheduler when to start threading than
177          * having a global use_threading switch based on just range size.
178          */
179         int min_iter_per_thread;
180 } ParallelRangeSettings;
181
182 BLI_INLINE void BLI_parallel_range_settings_defaults(
183         ParallelRangeSettings *settings);
184
185 void BLI_task_parallel_range(
186         const int start, const int stop,
187         void *userdata,
188         TaskParallelRangeFunc func,
189         const ParallelRangeSettings *settings);
190
191 typedef void (*TaskParallelListbaseFunc)(void *userdata,
192                                          struct Link *iter,
193                                          int index);
194 void BLI_task_parallel_listbase(
195         struct ListBase *listbase,
196         void *userdata,
197         TaskParallelListbaseFunc func,
198         const bool use_threading);
199
200 typedef struct MempoolIterData MempoolIterData;
201 typedef void (*TaskParallelMempoolFunc)(void *userdata,
202                                         MempoolIterData *iter);
203 void BLI_task_parallel_mempool(
204         struct BLI_mempool *mempool,
205         void *userdata,
206         TaskParallelMempoolFunc func,
207         const bool use_threading);
208
209 /* TODO(sergey): Think of a better place for this. */
210 BLI_INLINE void BLI_parallel_range_settings_defaults(
211         ParallelRangeSettings *settings)
212 {
213         memset(settings, 0, sizeof(*settings));
214         settings->use_threading = true;
215         settings->scheduling_mode = TASK_SCHEDULING_STATIC;
216         /* NOTE: Current value mimics old behavior, but it's not ideal by any
217          * means. Would be cool to find a common value which will work good enough
218          * for both static and dynamic scheduling.
219          */
220         settings->min_iter_per_thread = 1;
221 }
222
223 #ifdef __cplusplus
224 }
225 #endif
226
227 #endif