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-2017 Inria
4  * Copyright (C) 2009-2019 Université de Bordeaux
5  * Copyright (C) 2010-2015,2017,2018,2019 CNRS
6  * Copyright (C) 2011 Télécom-SudParis
7  * Copyright (C) 2016 Uppsala University
8  *
9  * StarPU is free software; you can redistribute it and/or modify
10  * it under the terms of the GNU Lesser General Public License as published by
11  * the Free Software Foundation; either version 2.1 of the License, or (at
12  * your option) any later version.
13  *
14  * StarPU is distributed in the hope that it will be useful, but
15  * WITHOUT ANY WARRANTY; without even the implied warranty of
16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
17  *
18  * See the GNU Lesser General Public License in COPYING.LGPL for more details.
19  */
20 
21 #ifndef __STARPU_TASK_H__
22 #define __STARPU_TASK_H__
23 
24 #include <starpu.h>
25 #include <errno.h>
26 #include <assert.h>
27 
28 #if defined STARPU_USE_CUDA && !defined STARPU_DONT_INCLUDE_CUDA_HEADERS
29 # include <cuda.h>
30 #endif
31 
32 #ifdef __cplusplus
33 extern "C"
34 {
35 #endif
36 
50 #define STARPU_NOWHERE ((1ULL)<<0)
51 
57 #define STARPU_CPU ((1ULL)<<1)
58 
64 #define STARPU_CUDA ((1ULL)<<3)
65 
71 #define STARPU_OPENCL ((1ULL)<<6)
72 
78 #define STARPU_MIC ((1ULL)<<7)
79 
85 #define STARPU_MPI_MS ((1ULL)<<9)
86 
91 #define STARPU_CODELET_SIMGRID_EXECUTE (1<<0)
92 
98 #define STARPU_CODELET_SIMGRID_EXECUTE_AND_INJECT (1<<1)
99 
104 #define STARPU_CODELET_NOPLANS (1<<2)
105 
110 #define STARPU_CUDA_ASYNC (1<<0)
111 
116 #define STARPU_OPENCL_ASYNC (1<<0)
117 
121 #define STARPU_MAIN_RAM 0
122 
123 
129 {
145 };
146 
148 {
150 #define STARPU_TASK_INVALID 0
160 };
161 
165 typedef void (*starpu_cpu_func_t)(void **, void*);
166 
170 typedef void (*starpu_cuda_func_t)(void **, void*);
171 
175 typedef void (*starpu_opencl_func_t)(void **, void*);
176 
180 typedef void (*starpu_mic_kernel_t)(void **, void*);
181 
186 
190 typedef void (*starpu_mpi_ms_kernel_t)(void **, void*);
191 
196 
204 #define STARPU_MULTIPLE_CPU_IMPLEMENTATIONS ((starpu_cpu_func_t) -1)
205 
213 #define STARPU_MULTIPLE_CUDA_IMPLEMENTATIONS ((starpu_cuda_func_t) -1)
214 
222 #define STARPU_MULTIPLE_OPENCL_IMPLEMENTATIONS ((starpu_opencl_func_t) -1)
223 
229 #define STARPU_VARIABLE_NBUFFERS (-1)
230 
236 #define STARPU_SPECIFIC_NODE_LOCAL (-1)
237 #define STARPU_SPECIFIC_NODE_CPU (-2)
238 #define STARPU_SPECIFIC_NODE_SLOW (-3)
239 #define STARPU_SPECIFIC_NODE_FAST (-4)
240 
241 struct starpu_task;
242 
251 {
266  uint32_t where;
267 
273  int (*can_execute)(unsigned workerid, struct starpu_task *task, unsigned nimpl);
274 
283 
290 
296  starpu_cpu_func_t cpu_func STARPU_DEPRECATED;
297 
303  starpu_cuda_func_t cuda_func STARPU_DEPRECATED;
304 
311 
328 
343 
350 
364 
371 
387 
403 
412 
426  int nbuffers;
427 
438 
451 
461  unsigned specific_nodes;
462 
471 
483  int *dyn_nodes;
484 
492 
502 
511 
516  const char *name;
517 
522  unsigned color;
523 
527  int flags;
528 };
529 
534 {
537 };
538 
549 {
557  const char *name;
558 
567 
575  int32_t where;
576 
584  int nbuffers;
585 
586  /* Keep dyn_handles, dyn_interfaces and dyn_modes before the
587  * equivalent static arrays, so we can detect dyn_handles
588  * being NULL while nbuffers being bigger that STARPU_NMAXBUFS
589  * (otherwise the overflow would put a non-NULL) */
590 
630 
650  void *interfaces[STARPU_NMAXBUFS];
666 
676 
691  void *cl_arg;
708  size_t cl_arg_size;
709 
726  void (*callback_func)(void *);
740 
754  void (*prologue_callback_func)(void *);
755 
766 
767  void (*prologue_callback_pop_func)(void *);
768  void *prologue_callback_pop_arg;
769 
779 
793  unsigned cl_arg_free:1;
794 
806  unsigned callback_arg_free:1;
807 
820 
834 
845  unsigned use_tag:1;
846 
858 
868  unsigned synchronous:1;
869 
879 
889  unsigned detach:1;
890 
906  unsigned destroy:1;
907 
917  unsigned regenerate:1;
918 
924  unsigned mf_skip:1;
925 
933  unsigned no_submitorder:1;
934 
940  unsigned scheduled:1;
941  unsigned prefetched:1;
942 
954  unsigned workerid;
955 
970  unsigned workerorder;
971 
984  uint32_t *workerids;
985 
995  unsigned workerids_len;
996 
1019 
1025  enum starpu_task_status status;
1026 
1034  int magic;
1035 
1045  unsigned type;
1046 
1053  unsigned color;
1054 
1061  unsigned sched_ctx;
1062 
1070 
1078 
1084 
1093 
1105  double flops;
1113  double predicted;
1114 
1123  double predicted_start;
1124 
1131 
1138 
1144 
1145 #ifdef STARPU_OPENMP
1146 
1150  struct starpu_omp_task *omp_task;
1151 #else
1152  void *omp_task;
1153 #endif
1154 
1159 
1167  void *sched_data;
1168 };
1169 
1170 #define STARPU_TASK_TYPE_NORMAL 0
1171 #define STARPU_TASK_TYPE_INTERNAL (1<<0)
1172 #define STARPU_TASK_TYPE_DATA_ACQUIRE (1<<1)
1173 
1179 /* Note: remember to update starpu_task_init as well */
1180 #define STARPU_TASK_INITIALIZER \
1181 { \
1182  .cl = NULL, \
1183  .where = -1, \
1184  .cl_arg = NULL, \
1185  .cl_arg_size = 0, \
1186  .callback_func = NULL, \
1187  .callback_arg = NULL, \
1188  .priority = STARPU_DEFAULT_PRIO, \
1189  .use_tag = 0, \
1190  .sequential_consistency = 1, \
1191  .synchronous = 0, \
1192  .execute_on_a_specific_worker = 0, \
1193  .workerorder = 0, \
1194  .bundle = NULL, \
1195  .detach = 1, \
1196  .destroy = 0, \
1197  .regenerate = 0, \
1198  .status = STARPU_TASK_INVALID, \
1199  .profiling_info = NULL, \
1200  .predicted = NAN, \
1201  .predicted_transfer = NAN, \
1202  .predicted_start = NAN, \
1203  .starpu_private = NULL, \
1204  .magic = 42, \
1205  .type = 0, \
1206  .color = 0, \
1207  .sched_ctx = STARPU_NMAX_SCHED_CTXS, \
1208  .hypervisor_tag = 0, \
1209  .flops = 0.0, \
1210  .scheduled = 0, \
1211  .prefetched = 0, \
1212  .dyn_handles = NULL, \
1213  .dyn_interfaces = NULL, \
1214  .dyn_modes = NULL, \
1215  .name = NULL, \
1216  .possibly_parallel = 0 \
1217 }
1218 
1224 #define STARPU_TASK_GET_NBUFFERS(task) ((unsigned)((task)->cl->nbuffers == STARPU_VARIABLE_NBUFFERS ? ((task)->nbuffers) : ((task)->cl->nbuffers)))
1225 
1233 #define STARPU_TASK_GET_HANDLE(task, i) (((task)->dyn_handles) ? (task)->dyn_handles[i] : (task)->handles[i])
1234 #define STARPU_TASK_GET_HANDLES(task) (((task)->dyn_handles) ? (task)->dyn_handles : (task)->handles)
1235 
1243 #define STARPU_TASK_SET_HANDLE(task, handle, i) \
1244  do { if ((task)->dyn_handles) (task)->dyn_handles[i] = handle; else (task)->handles[i] = handle; } while(0)
1245 
1253 #define STARPU_CODELET_GET_MODE(codelet, i) \
1254  (((codelet)->dyn_modes) ? (codelet)->dyn_modes[i] : (assert(i < STARPU_NMAXBUFS), (codelet)->modes[i]))
1255 
1263 #define STARPU_CODELET_SET_MODE(codelet, mode, i) \
1264  do { if ((codelet)->dyn_modes) (codelet)->dyn_modes[i] = mode; else (codelet)->modes[i] = mode; } while(0)
1265 
1273 #define STARPU_TASK_GET_MODE(task, i) \
1274  ((task)->cl->nbuffers == STARPU_VARIABLE_NBUFFERS || (task)->dyn_modes ? \
1275  (((task)->dyn_modes) ? (task)->dyn_modes[i] : (task)->modes[i]) : \
1276  STARPU_CODELET_GET_MODE((task)->cl, i) )
1277 
1285 #define STARPU_TASK_SET_MODE(task, mode, i) \
1286  do { \
1287  if ((task)->cl->nbuffers == STARPU_VARIABLE_NBUFFERS || (task)->cl->nbuffers > STARPU_NMAXBUFS) \
1288  if ((task)->dyn_modes) (task)->dyn_modes[i] = mode; else (task)->modes[i] = mode; \
1289  else \
1290  STARPU_CODELET_SET_MODE((task)->cl, mode, i); \
1291  } while(0)
1292 
1300 #define STARPU_CODELET_GET_NODE(codelet, i) (((codelet)->dyn_nodes) ? (codelet)->dyn_nodes[i] : (codelet)->nodes[i])
1301 
1309 #define STARPU_CODELET_SET_NODE(codelet, __node, i) \
1310  do { if ((codelet)->dyn_nodes) (codelet)->dyn_nodes[i] = __node; else (codelet)->nodes[i] = __node; } while(0)
1311 
1319 void starpu_task_init(struct starpu_task *task);
1320 
1332 void starpu_task_clean(struct starpu_task *task);
1333 
1345 
1354 void starpu_task_destroy(struct starpu_task *task);
1355 
1373 int starpu_task_submit(struct starpu_task *task) STARPU_WARN_UNUSED_RESULT;
1374 
1380 int starpu_task_submit_to_ctx(struct starpu_task *task, unsigned sched_ctx_id);
1381 
1382 int starpu_task_finished(struct starpu_task *task) STARPU_WARN_UNUSED_RESULT;
1383 
1391 int starpu_task_wait(struct starpu_task *task) STARPU_WARN_UNUSED_RESULT;
1392 
1398 int starpu_task_wait_array(struct starpu_task **tasks, unsigned nb_tasks) STARPU_WARN_UNUSED_RESULT;
1399 
1405 int starpu_task_wait_for_all(void);
1406 
1412 int starpu_task_wait_for_n_submitted(unsigned n);
1413 
1418 int starpu_task_wait_for_all_in_ctx(unsigned sched_ctx_id);
1419 
1425 int starpu_task_wait_for_n_submitted_in_ctx(unsigned sched_ctx_id, unsigned n);
1426 
1431 
1437 int starpu_task_nready(void);
1438 
1442 int starpu_task_nsubmitted(void);
1443 
1456 void starpu_iteration_push(unsigned long iteration);
1457 
1463 void starpu_iteration_pop(void);
1464 
1465 void starpu_do_schedule(void);
1466 
1472 void starpu_codelet_init(struct starpu_codelet *cl);
1473 
1478 
1484 struct starpu_task *starpu_task_get_current(void);
1485 
1496 int starpu_task_get_current_data_node(unsigned i);
1497 
1501 const char *starpu_task_get_model_name(struct starpu_task *task);
1502 
1507 const char *starpu_task_get_name(struct starpu_task *task);
1508 
1512 struct starpu_task *starpu_task_dup(struct starpu_task *task);
1513 
1518 void starpu_task_set_implementation(struct starpu_task *task, unsigned impl);
1519 
1524 unsigned starpu_task_get_implementation(struct starpu_task *task);
1525 
1530 void starpu_create_sync_task(starpu_tag_t sync_tag, unsigned ndeps, starpu_tag_t *deps, void (*callback)(void *), void *callback_arg);
1531 
1535 void starpu_create_callback_task(void (*callback)(void *), void *callback_arg);
1536 
1539 #ifdef __cplusplus
1540 }
1541 #endif
1542 
1543 #endif /* __STARPU_TASK_H__ */
void * prologue_callback_arg
Definition: starpu_task.h:765
unsigned color
Definition: starpu_task.h:522
unsigned use_tag
Definition: starpu_task.h:845
starpu_opencl_func_t opencl_func
Definition: starpu_task.h:310
char cuda_flags[STARPU_MAXIMPLEMENTATIONS]
Definition: starpu_task.h:349
Definition: starpu_task.h:250
starpu_opencl_func_t opencl_funcs[STARPU_MAXIMPLEMENTATIONS]
Definition: starpu_task.h:363
Definition: starpu_task.h:133
Definition: starpu_profiling.h:49
enum starpu_data_access_mode modes[STARPU_NMAXBUFS]
Definition: starpu_task.h:437
int nbuffers
Definition: starpu_task.h:584
void ** dyn_interfaces
Definition: starpu_task.h:612
void(* starpu_cpu_func_t)(void **, void *)
Definition: starpu_task.h:165
unsigned regenerate
Definition: starpu_task.h:917
int max_parallelism
Definition: starpu_task.h:289
int starpu_task_submit_to_ctx(struct starpu_task *task, unsigned sched_ctx_id)
void starpu_create_callback_task(void(*callback)(void *), void *callback_arg)
uint32_t * workerids
Definition: starpu_task.h:984
unsigned execute_on_a_specific_worker
Definition: starpu_task.h:878
void(* starpu_opencl_func_t)(void **, void *)
Definition: starpu_task.h:175
int starpu_task_nready(void)
unsigned possibly_parallel
Definition: starpu_task.h:1077
unsigned type
Definition: starpu_task.h:1045
struct starpu_omp_task * omp_task
Definition: starpu_task.h:1150
double predicted
Definition: starpu_task.h:1113
starpu_mic_func_t mic_funcs[STARPU_MAXIMPLEMENTATIONS]
Definition: starpu_task.h:386
#define STARPU_ATTRIBUTE_MALLOC
Definition: starpu_util.h:114
int priority
Definition: starpu_task.h:1018
unsigned workerids_len
Definition: starpu_task.h:995
struct starpu_task * prev
Definition: starpu_task.h:1130
int starpu_task_submit(struct starpu_task *task) STARPU_WARN_UNUSED_RESULT
Definition: starpu_task.h:130
char opencl_flags[STARPU_MAXIMPLEMENTATIONS]
Definition: starpu_task.h:370
int starpu_task_nsubmitted(void)
struct _starpu_task_bundle * starpu_task_bundle_t
Definition: starpu_task_bundle.h:42
unsigned sequential_consistency
Definition: starpu_task.h:857
void starpu_iteration_pop(void)
unsigned workerid
Definition: starpu_task.h:954
const char * starpu_task_get_name(struct starpu_task *task)
size_t cl_arg_size
Definition: starpu_task.h:708
unsigned detach
Definition: starpu_task.h:889
int nodes[STARPU_NMAXBUFS]
Definition: starpu_task.h:470
const char * cpu_funcs_name[STARPU_MAXIMPLEMENTATIONS]
Definition: starpu_task.h:411
int magic
Definition: starpu_task.h:1034
struct starpu_profiling_task_info * profiling_info
Definition: starpu_task.h:1092
void starpu_task_clean(struct starpu_task *task)
unsigned sched_ctx
Definition: starpu_task.h:1061
void starpu_task_destroy(struct starpu_task *task)
unsigned nb_termination_call_required
Definition: starpu_task.h:1158
int starpu_task_wait_for_all(void)
starpu_cpu_func_t cpu_func
Definition: starpu_task.h:296
unsigned specific_nodes
Definition: starpu_task.h:461
void(* starpu_mpi_ms_kernel_t)(void **, void *)
Definition: starpu_task.h:190
void * cl_arg
Definition: starpu_task.h:691
starpu_data_handle_t * dyn_handles
Definition: starpu_task.h:604
uint32_t where
Definition: starpu_task.h:266
Definition: starpu_task.h:151
Definition: starpu_task.h:139
unsigned mf_skip
Definition: starpu_task.h:924
starpu_mpi_ms_func_t mpi_ms_funcs[STARPU_MAXIMPLEMENTATIONS]
Definition: starpu_task.h:402
Definition: starpu_task.h:154
unsigned no_submitorder
Definition: starpu_task.h:933
struct starpu_perfmodel * model
Definition: starpu_task.h:491
int starpu_task_wait_array(struct starpu_task **tasks, unsigned nb_tasks) STARPU_WARN_UNUSED_RESULT
struct starpu_task * next
Definition: starpu_task.h:1137
enum starpu_codelet_type type
Definition: starpu_task.h:282
starpu_cuda_func_t cuda_funcs[STARPU_MAXIMPLEMENTATIONS]
Definition: starpu_task.h:342
void * starpu_private
Definition: starpu_task.h:1143
starpu_mic_kernel_t(* starpu_mic_func_t)(void)
Definition: starpu_task.h:185
void(* starpu_mic_kernel_t)(void **, void *)
Definition: starpu_task.h:180
uint64_t starpu_tag_t
Definition: starpu_task_dep.h:129
struct starpu_task * starpu_task_dup(struct starpu_task *task)
unsigned color
Definition: starpu_task.h:1053
const char * name
Definition: starpu_task.h:516
Definition: starpu_task.h:153
int starpu_task_wait_for_all_in_ctx(unsigned sched_ctx_id)
Definition: starpu_task.h:548
starpu_task_status
Definition: starpu_task.h:147
starpu_mpi_ms_kernel_t(* starpu_mpi_ms_func_t)(void)
Definition: starpu_task.h:195
const char * name
Definition: starpu_task.h:557
void starpu_iteration_push(unsigned long iteration)
starpu_tag_t tag_id
Definition: starpu_task.h:778
unsigned synchronous
Definition: starpu_task.h:868
void starpu_task_set_implementation(struct starpu_task *task, unsigned impl)
int starpu_task_wait_for_n_submitted(unsigned n)
unsigned starpu_task_get_implementation(struct starpu_task *task)
void * sched_data
Definition: starpu_task.h:1167
int starpu_task_wait(struct starpu_task *task) STARPU_WARN_UNUSED_RESULT
enum starpu_data_access_mode * dyn_modes
Definition: starpu_task.h:629
int * dyn_nodes
Definition: starpu_task.h:483
struct _starpu_data_state * starpu_data_handle_t
Definition: starpu_data.h:46
#define STARPU_NMAXWORKERS
Definition: starpu_config.h:115
void starpu_task_init(struct starpu_task *task)
double predicted_transfer
Definition: starpu_task.h:1122
unsigned cl_arg_free
Definition: starpu_task.h:793
void starpu_codelet_init(struct starpu_codelet *cl)
Definition: starpu_task.h:157
Definition: starpu_task.h:149
Definition: starpu_task.h:158
unsigned prologue_callback_pop_arg_free
Definition: starpu_task.h:833
int32_t where
Definition: starpu_task.h:575
unsigned char * handles_sequential_consistency
Definition: starpu_task.h:675
struct starpu_task * starpu_task_create(void) STARPU_ATTRIBUTE_MALLOC
#define STARPU_MAXIMPLEMENTATIONS
Definition: starpu_config.h:117
Definition: starpu_perfmodel.h:190
const char * starpu_task_get_model_name(struct starpu_task *task)
unsigned long per_worker_stats[STARPU_NMAXWORKERS]
Definition: starpu_task.h:510
Definition: starpu_task.h:155
int nbuffers
Definition: starpu_task.h:426
int starpu_task_wait_for_n_submitted_in_ctx(unsigned sched_ctx_id, unsigned n)
struct starpu_perfmodel * energy_model
Definition: starpu_task.h:501
int(* can_execute)(unsigned workerid, struct starpu_task *task, unsigned nimpl)
Definition: starpu_task.h:273
enum starpu_data_access_mode * dyn_modes
Definition: starpu_task.h:450
starpu_data_access_mode
Definition: starpu_data.h:56
double flops
Definition: starpu_task.h:1105
unsigned destroy
Definition: starpu_task.h:906
void starpu_create_sync_task(starpu_tag_t sync_tag, unsigned ndeps, starpu_tag_t *deps, void(*callback)(void *), void *callback_arg)
void starpu_codelet_display_stats(struct starpu_codelet *cl)
starpu_task_bundle_t bundle
Definition: starpu_task.h:1083
unsigned callback_arg_free
Definition: starpu_task.h:806
starpu_codelet_type
Definition: starpu_task.h:128
Definition: starpu_task.h:156
#define STARPU_NMAXBUFS
Definition: starpu_config.h:109
void(* starpu_cuda_func_t)(void **, void *)
Definition: starpu_task.h:170
void * callback_arg
Definition: starpu_task.h:739
starpu_cuda_func_t cuda_func
Definition: starpu_task.h:303
Definition: starpu_task.h:533
Definition: starpu_task.h:159
unsigned workerorder
Definition: starpu_task.h:970
int flags
Definition: starpu_task.h:527
unsigned prologue_callback_arg_free
Definition: starpu_task.h:819
starpu_cpu_func_t cpu_funcs[STARPU_MAXIMPLEMENTATIONS]
Definition: starpu_task.h:327
struct starpu_task * starpu_task_get_current(void)
int starpu_task_get_current_data_node(unsigned i)
starpu_data_handle_t handle
Definition: starpu_task.h:535
struct starpu_codelet * cl
Definition: starpu_task.h:566
unsigned scheduled
Definition: starpu_task.h:940
int hypervisor_tag
Definition: starpu_task.h:1069
int starpu_task_wait_for_no_ready(void)