StarPU Handbook
starpu_task.h
Go to the documentation of this file.
1 /* StarPU --- Runtime system for heterogeneous multicore architectures.
2  *
3  * Copyright (C) 2011-2014 Inria
4  * Copyright (C) 2009-2018 Université de Bordeaux
5  * Copyright (C) 2010-2015,2017 CNRS
6  * Copyright (C) 2011 Télécom-SudParis
7  *
8  * StarPU is free software; you can redistribute it and/or modify
9  * it under the terms of the GNU Lesser General Public License as published by
10  * the Free Software Foundation; either version 2.1 of the License, or (at
11  * your option) any later version.
12  *
13  * StarPU is distributed in the hope that it will be useful, but
14  * WITHOUT ANY WARRANTY; without even the implied warranty of
15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
16  *
17  * See the GNU Lesser General Public License in COPYING.LGPL for more details.
18  */
19 
20 #ifndef __STARPU_TASK_H__
21 #define __STARPU_TASK_H__
22 
23 #include <starpu.h>
24 #include <starpu_data.h>
25 #include <starpu_util.h>
26 #include <starpu_task_bundle.h>
27 #include <errno.h>
28 #include <assert.h>
29 
30 #if defined STARPU_USE_CUDA && !defined STARPU_DONT_INCLUDE_CUDA_HEADERS
31 # include <cuda.h>
32 #endif
33 
34 #ifdef __cplusplus
35 extern "C"
36 {
37 #endif
38 
39 #define STARPU_NOWHERE ((1ULL)<<0)
40 #define STARPU_CPU ((1ULL)<<1)
41 #define STARPU_CUDA ((1ULL)<<3)
42 #define STARPU_OPENCL ((1ULL)<<6)
43 #define STARPU_MIC ((1ULL)<<7)
44 #define STARPU_SCC ((1ULL)<<8)
45 
46 #define STARPU_CODELET_SIMGRID_EXECUTE (1<<0)
47 #define STARPU_CUDA_ASYNC (1<<0)
48 #define STARPU_OPENCL_ASYNC (1<<0)
49 
51 {
55 };
56 
58 {
60 #define STARPU_TASK_INVALID 0
68  STARPU_TASK_STOPPED
69 };
70 
71 typedef uint64_t starpu_tag_t;
72 
73 typedef void (*starpu_cpu_func_t)(void **, void*);
74 typedef void (*starpu_cuda_func_t)(void **, void*);
75 typedef void (*starpu_opencl_func_t)(void **, void*);
76 typedef void (*starpu_mic_kernel_t)(void **, void*);
77 typedef void (*starpu_scc_kernel_t)(void **, void*);
78 
81 
82 #define STARPU_MULTIPLE_CPU_IMPLEMENTATIONS ((starpu_cpu_func_t) -1)
83 #define STARPU_MULTIPLE_CUDA_IMPLEMENTATIONS ((starpu_cuda_func_t) -1)
84 #define STARPU_MULTIPLE_OPENCL_IMPLEMENTATIONS ((starpu_opencl_func_t) -1)
85 
86 #define STARPU_VARIABLE_NBUFFERS (-1)
87 
88 struct starpu_task;
90 {
91  uint32_t where;
92  int (*can_execute)(unsigned workerid, struct starpu_task *task, unsigned nimpl);
95 
96  starpu_cpu_func_t cpu_func STARPU_DEPRECATED;
97  starpu_cuda_func_t cuda_func STARPU_DEPRECATED;
98  starpu_opencl_func_t opencl_func STARPU_DEPRECATED;
99 
107 
109 
110  int nbuffers;
113 
114  unsigned specific_nodes;
116  int *dyn_nodes;
117 
120 
122 
123  const char *name;
124  unsigned color;
125 
126  int flags;
127 };
128 
130 {
131  const char *name;
132 
134 
135  int nbuffers;
136 
138  void *interfaces[STARPU_NMAXBUFS];
140 
144 
145  void *cl_arg;
146  size_t cl_arg_size;
147 
148  void (*callback_func)(void *);
150  /* must StarPU release callback_arg ? - 0 by default */
151 
152  void (*prologue_callback_func)(void *);
154 
155  void (*prologue_callback_pop_func)(void *);
156  void *prologue_callback_pop_arg;
157 
158  starpu_tag_t tag_id;
159 
160  unsigned cl_arg_free:1;
161  unsigned callback_arg_free:1;
162  /* must StarPU release prologue_callback_arg ? - 0 by default */
164  /* must StarPU release prologue_callback_pop_arg ? - 0 by default */
165  unsigned prologue_callback_pop_arg_free:1;
166 
167  unsigned use_tag:1;
169  unsigned synchronous:1;
171 
172  unsigned detach:1;
173  unsigned destroy:1;
174  unsigned regenerate:1;
175 
176  unsigned int mf_skip:1;
177 
178  unsigned scheduled:1;
179  unsigned prefetched:1;
180 
181  unsigned workerid;
182  unsigned workerorder;
183 
184  int priority;
185 
186  enum starpu_task_status status;
187 
188  int magic;
189  unsigned type;
190  unsigned color;
191 
192  unsigned sched_ctx;
194  unsigned possibly_parallel;
195 
197 
199 
200  double flops;
201  double predicted;
203 
204  struct starpu_task *prev;
205  struct starpu_task *next;
207 #ifdef STARPU_OPENMP
208  struct starpu_omp_task *omp_task;
209 #else
210  void *omp_task;
211 #endif
212 };
213 
214 #define STARPU_TASK_TYPE_NORMAL 0
215 #define STARPU_TASK_TYPE_INTERNAL (1<<0)
216 #define STARPU_TASK_TYPE_DATA_ACQUIRE (1<<1)
217 
218 /* Note: remember to update starpu_task_init as well */
219 #define STARPU_TASK_INITIALIZER \
220 { \
221  .cl = NULL, \
222  .cl_arg = NULL, \
223  .cl_arg_size = 0, \
224  .callback_func = NULL, \
225  .callback_arg = NULL, \
226  .priority = STARPU_DEFAULT_PRIO, \
227  .use_tag = 0, \
228  .sequential_consistency = 1, \
229  .synchronous = 0, \
230  .execute_on_a_specific_worker = 0, \
231  .workerorder = 0, \
232  .bundle = NULL, \
233  .detach = 1, \
234  .destroy = 0, \
235  .regenerate = 0, \
236  .status = STARPU_TASK_INVALID, \
237  .profiling_info = NULL, \
238  .predicted = NAN, \
239  .predicted_transfer = NAN, \
240  .starpu_private = NULL, \
241  .magic = 42, \
242  .type = 0, \
243  .color = 0, \
244  .sched_ctx = STARPU_NMAX_SCHED_CTXS, \
245  .hypervisor_tag = 0, \
246  .flops = 0.0, \
247  .scheduled = 0, \
248  .prefetched = 0, \
249  .dyn_handles = NULL, \
250  .dyn_interfaces = NULL, \
251  .dyn_modes = NULL, \
252  .name = NULL, \
253  .possibly_parallel = 0 \
254 }
255 
256 #define STARPU_TASK_GET_NBUFFERS(task) ((unsigned)((task)->cl->nbuffers == STARPU_VARIABLE_NBUFFERS ? ((task)->nbuffers) : ((task)->cl->nbuffers)))
257 
258 #define STARPU_TASK_GET_HANDLE(task, i) (((task)->dyn_handles) ? (task)->dyn_handles[i] : (task)->handles[i])
259 #define STARPU_TASK_GET_HANDLES(task) (((task)->dyn_handles) ? (task)->dyn_handles : (task)->handles)
260 #define STARPU_TASK_SET_HANDLE(task, handle, i) do { if ((task)->dyn_handles) (task)->dyn_handles[i] = handle; else (task)->handles[i] = handle; } while(0)
261 
262 #define STARPU_CODELET_GET_MODE(codelet, i) (((codelet)->dyn_modes) ? (codelet)->dyn_modes[i] : (assert(i < STARPU_NMAXBUFS), (codelet)->modes[i]))
263 #define STARPU_CODELET_SET_MODE(codelet, mode, i) do { if ((codelet)->dyn_modes) (codelet)->dyn_modes[i] = mode; else (codelet)->modes[i] = mode; } while(0)
264 
265 #define STARPU_TASK_GET_MODE(task, i) ((task)->cl->nbuffers == STARPU_VARIABLE_NBUFFERS || (task)->dyn_modes ? \
266  (((task)->dyn_modes) ? (task)->dyn_modes[i] : (task)->modes[i]) : \
267  STARPU_CODELET_GET_MODE((task)->cl, i) )
268 #define STARPU_TASK_SET_MODE(task, mode, i) do { \
269  if ((task)->cl->nbuffers == STARPU_VARIABLE_NBUFFERS || (task)->cl->nbuffers > STARPU_NMAXBUFS) \
270  if ((task)->dyn_modes) (task)->dyn_modes[i] = mode; else (task)->modes[i] = mode; \
271  else \
272  STARPU_CODELET_SET_MODE((task)->cl, mode, i); \
273  } while(0)
274 
275 #define STARPU_CODELET_GET_NODE(codelet, i) (((codelet)->dyn_nodes) ? (codelet)->dyn_nodes[i] : (codelet)->nodes[i])
276 #define STARPU_CODELET_SET_NODE(codelet, __node, i) do { if ((codelet)->dyn_nodes) (codelet)->dyn_nodes[i] = __node; else (codelet)->nodes[i] = __node; } while(0)
277 
278 void starpu_tag_declare_deps(starpu_tag_t id, unsigned ndeps, ...);
279 void starpu_tag_declare_deps_array(starpu_tag_t id, unsigned ndeps, starpu_tag_t *array);
280 
281 void starpu_task_declare_deps_array(struct starpu_task *task, unsigned ndeps, struct starpu_task *task_array[]);
282 
283 int starpu_task_get_task_succs(struct starpu_task *task, unsigned ndeps, struct starpu_task *task_array[]);
284 int starpu_task_get_task_scheduled_succs(struct starpu_task *task, unsigned ndeps, struct starpu_task *task_array[]);
285 
286 int starpu_tag_wait(starpu_tag_t id);
287 int starpu_tag_wait_array(unsigned ntags, starpu_tag_t *id);
288 
289 void starpu_tag_notify_from_apps(starpu_tag_t id);
290 
291 void starpu_tag_restart(starpu_tag_t id);
292 
293 void starpu_tag_remove(starpu_tag_t id);
294 
295 void starpu_task_init(struct starpu_task *task);
296 void starpu_task_clean(struct starpu_task *task);
297 
299 
300 void starpu_task_destroy(struct starpu_task *task);
302 int starpu_task_submit_to_ctx(struct starpu_task *task, unsigned sched_ctx_id);
303 
304 int starpu_task_finished(struct starpu_task *task) STARPU_WARN_UNUSED_RESULT;
305 
307 
308 int starpu_task_wait_for_all(void);
309 int starpu_task_wait_for_n_submitted(unsigned n);
310 
311 int starpu_task_wait_for_all_in_ctx(unsigned sched_ctx_id);
312 int starpu_task_wait_for_n_submitted_in_ctx(unsigned sched_ctx_id, unsigned n);
313 
315 
316 int starpu_task_nready(void);
317 int starpu_task_nsubmitted(void);
318 
319 void starpu_iteration_push(unsigned long iteration);
320 void starpu_iteration_pop(void);
321 
322 void starpu_do_schedule(void);
323 
325 
327 
329 
330 const char *starpu_task_get_model_name(struct starpu_task *task);
331 const char *starpu_task_get_name(struct starpu_task *task);
332 
334 void starpu_parallel_task_barrier_init_n(struct starpu_task *task, int worker_size);
335 
336 struct starpu_task *starpu_task_dup(struct starpu_task *task);
337 
338 void starpu_task_set_implementation(struct starpu_task *task, unsigned impl);
339 unsigned starpu_task_get_implementation(struct starpu_task *task);
340 
341 #ifdef __cplusplus
342 }
343 #endif
344 
345 #endif /* __STARPU_TASK_H__ */
unsigned color
Definition: starpu_task.h:124
Definition: starpu_task.h:65
struct starpu_perfmodel * energy_model
Definition: starpu_task.h:119
unsigned use_tag
Definition: starpu_task.h:167
void * prologue_callback_arg
Definition: starpu_task.h:153
starpu_opencl_func_t opencl_func
Definition: starpu_task.h:98
char cuda_flags[STARPU_MAXIMPLEMENTATIONS]
Definition: starpu_task.h:102
Definition: starpu_task.h:89
starpu_opencl_func_t opencl_funcs[STARPU_MAXIMPLEMENTATIONS]
Definition: starpu_task.h:103
starpu_scc_func_t scc_funcs[STARPU_MAXIMPLEMENTATIONS]
Definition: starpu_task.h:106
Definition: starpu_profiling.h:34
enum starpu_data_access_mode modes[STARPU_NMAXBUFS]
Definition: starpu_task.h:111
int nbuffers
Definition: starpu_task.h:135
void(* starpu_mic_kernel_t)(void **, void *)
Definition: starpu_task.h:76
unsigned regenerate
Definition: starpu_task.h:174
int max_parallelism
Definition: starpu_task.h:94
starpu_mic_kernel_t(* starpu_mic_func_t)(void)
Definition: starpu_task.h:79
void ** dyn_interfaces
Definition: starpu_task.h:142
int starpu_task_submit_to_ctx(struct starpu_task *task, unsigned sched_ctx_id)
struct starpu_profiling_task_info * profiling_info
Definition: starpu_task.h:198
enum starpu_data_access_mode * dyn_modes
Definition: starpu_task.h:143
unsigned execute_on_a_specific_worker
Definition: starpu_task.h:170
int * dyn_nodes
Definition: starpu_task.h:116
int starpu_task_nready(void)
#define STARPU_TASK_INVALID
Definition: starpu_task.h:60
unsigned type
Definition: starpu_task.h:189
struct starpu_codelet * cl
Definition: starpu_task.h:133
void starpu_tag_declare_deps(starpu_tag_t id, unsigned ndeps,...)
double predicted
Definition: starpu_task.h:201
starpu_mic_func_t mic_funcs[STARPU_MAXIMPLEMENTATIONS]
Definition: starpu_task.h:105
struct starpu_perfmodel * model
Definition: starpu_task.h:118
struct starpu_task * prev
Definition: starpu_task.h:204
#define STARPU_ATTRIBUTE_MALLOC
Definition: starpu_util.h:62
Definition: starpu_task.h:61
int priority
Definition: starpu_task.h:184
void * callback_arg
Definition: starpu_task.h:149
int starpu_task_submit(struct starpu_task *task) STARPU_WARN_UNUSED_RESULT
char opencl_flags[STARPU_MAXIMPLEMENTATIONS]
Definition: starpu_task.h:104
int starpu_task_nsubmitted(void)
unsigned sequential_consistency
Definition: starpu_task.h:168
void starpu_iteration_pop(void)
unsigned workerid
Definition: starpu_task.h:181
void starpu_tag_restart(starpu_tag_t id)
Definition: starpu_task.h:54
Definition: starpu_task.h:53
size_t cl_arg_size
Definition: starpu_task.h:146
unsigned detach
Definition: starpu_task.h:172
int nodes[STARPU_NMAXBUFS]
Definition: starpu_task.h:115
int magic
Definition: starpu_task.h:188
void starpu_task_clean(struct starpu_task *task)
unsigned sched_ctx
Definition: starpu_task.h:192
void starpu_task_destroy(struct starpu_task *task)
void(* starpu_cuda_func_t)(void **, void *)
Definition: starpu_task.h:74
int starpu_task_wait_for_all(void)
starpu_cpu_func_t cpu_func
Definition: starpu_task.h:96
unsigned specific_nodes
Definition: starpu_task.h:114
uint32_t where
Definition: starpu_task.h:91
Definition: starpu_task.h:52
const char * name
Definition: starpu_task.h:123
Definition: starpu_task.h:62
enum starpu_codelet_type type
Definition: starpu_task.h:93
starpu_cuda_func_t cuda_funcs[STARPU_MAXIMPLEMENTATIONS]
Definition: starpu_task.h:101
void * cl_arg
Definition: starpu_task.h:145
struct starpu_task * starpu_task_create(void) STARPU_ATTRIBUTE_MALLOC
struct _starpu_task_bundle * starpu_task_bundle_t
Definition: starpu_task_bundle.h:30
starpu_data_handle_t * dyn_handles
Definition: starpu_task.h:141
void starpu_parallel_task_barrier_init(struct starpu_task *task, int workerid)
const char * starpu_task_get_name(struct starpu_task *task)
int starpu_task_wait_for_all_in_ctx(unsigned sched_ctx_id)
Definition: starpu_task.h:129
int(* can_execute)(unsigned workerid, struct starpu_task *task, unsigned nimpl)
Definition: starpu_task.h:92
starpu_task_status
Definition: starpu_task.h:57
void starpu_iteration_push(unsigned long iteration)
starpu_scc_kernel_t(* starpu_scc_func_t)(void)
Definition: starpu_task.h:80
starpu_tag_t tag_id
Definition: starpu_task.h:158
unsigned synchronous
Definition: starpu_task.h:169
void starpu_task_set_implementation(struct starpu_task *task, unsigned impl)
int starpu_tag_wait(starpu_tag_t id)
int starpu_task_wait_for_n_submitted(unsigned n)
unsigned starpu_task_get_implementation(struct starpu_task *task)
void starpu_tag_remove(starpu_tag_t id)
struct starpu_task * next
Definition: starpu_task.h:205
const char * starpu_task_get_model_name(struct starpu_task *task)
uint64_t starpu_tag_t
Definition: starpu_task.h:71
int starpu_task_wait(struct starpu_task *task) STARPU_WARN_UNUSED_RESULT
void(* starpu_cpu_func_t)(void **, void *)
Definition: starpu_task.h:73
unsigned color
Definition: starpu_task.h:190
#define STARPU_NMAXWORKERS
Definition: starpu_config.h:102
void starpu_parallel_task_barrier_init_n(struct starpu_task *task, int worker_size)
void starpu_task_init(struct starpu_task *task)
double predicted_transfer
Definition: starpu_task.h:202
const char * cpu_funcs_name[STARPU_MAXIMPLEMENTATIONS]
Definition: starpu_task.h:108
unsigned cl_arg_free
Definition: starpu_task.h:160
void starpu_codelet_init(struct starpu_codelet *cl)
struct starpu_task * starpu_task_get_current(void)
#define STARPU_MAXIMPLEMENTATIONS
Definition: starpu_config.h:104
Definition: starpu_perfmodel.h:127
unsigned long per_worker_stats[STARPU_NMAXWORKERS]
Definition: starpu_task.h:121
int starpu_tag_wait_array(unsigned ntags, starpu_tag_t *id)
int nbuffers
Definition: starpu_task.h:110
struct starpu_task * starpu_task_dup(struct starpu_task *task)
Definition: starpu_task.h:64
unsigned int mf_skip
Definition: starpu_task.h:176
int starpu_task_get_task_succs(struct starpu_task *task, unsigned ndeps, struct starpu_task *task_array[])
void starpu_task_declare_deps_array(struct starpu_task *task, unsigned ndeps, struct starpu_task *task_array[])
void starpu_tag_declare_deps_array(starpu_tag_t id, unsigned ndeps, starpu_tag_t *array)
int starpu_task_wait_for_n_submitted_in_ctx(unsigned sched_ctx_id, unsigned n)
#define STARPU_WARN_UNUSED_RESULT
Definition: starpu_util.h:96
starpu_data_access_mode
Definition: starpu_data.h:33
double flops
Definition: starpu_task.h:200
Definition: starpu_task.h:66
struct _starpu_data_state * starpu_data_handle_t
Definition: starpu_data.h:30
unsigned destroy
Definition: starpu_task.h:173
void starpu_codelet_display_stats(struct starpu_codelet *cl)
starpu_task_bundle_t bundle
Definition: starpu_task.h:196
unsigned callback_arg_free
Definition: starpu_task.h:161
void(* starpu_opencl_func_t)(void **, void *)
Definition: starpu_task.h:75
starpu_codelet_type
Definition: starpu_task.h:50
void starpu_tag_notify_from_apps(starpu_tag_t id)
#define STARPU_NMAXBUFS
Definition: starpu_config.h:96
Definition: starpu_task.h:63
Definition: starpu_task.h:67
starpu_cuda_func_t cuda_func
Definition: starpu_task.h:97
int starpu_task_get_task_scheduled_succs(struct starpu_task *task, unsigned ndeps, struct starpu_task *task_array[])
unsigned workerorder
Definition: starpu_task.h:182
const char * name
Definition: starpu_task.h:131
unsigned prologue_callback_arg_free
Definition: starpu_task.h:163
starpu_cpu_func_t cpu_funcs[STARPU_MAXIMPLEMENTATIONS]
Definition: starpu_task.h:100
int flags
Definition: starpu_task.h:126
void(* starpu_scc_kernel_t)(void **, void *)
Definition: starpu_task.h:77
enum starpu_data_access_mode * dyn_modes
Definition: starpu_task.h:112
void * starpu_private
Definition: starpu_task.h:206
unsigned scheduled
Definition: starpu_task.h:178
int hypervisor_tag
Definition: starpu_task.h:193
int starpu_task_wait_for_no_ready(void)