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 
724  void (*callback_func)(void *);
736 
750  void (*prologue_callback_func)(void *);
761 
762  void (*prologue_callback_pop_func)(void *);
763  void *prologue_callback_pop_arg;
764 
774 
788  unsigned cl_arg_free:1;
798  unsigned callback_arg_free:1;
820 
831  unsigned use_tag:1;
832 
843 
853  unsigned synchronous:1;
854 
864 
874  unsigned detach:1;
875 
891  unsigned destroy:1;
892 
902  unsigned regenerate:1;
903 
909  unsigned mf_skip:1;
910 
916  unsigned no_submitorder:1;
917 
923  unsigned scheduled:1;
924  unsigned prefetched:1;
925 
937  unsigned workerid;
938 
953  unsigned workerorder;
954 
964  uint32_t *workerids;
965 
972  unsigned workerids_len;
973 
995  int priority;
996 
1002  enum starpu_task_status status;
1003 
1011  int magic;
1012 
1022  unsigned type;
1023 
1030  unsigned color;
1031 
1038  unsigned sched_ctx;
1039 
1047 
1055 
1061 
1068 
1080  double flops;
1088  double predicted;
1089 
1098  double predicted_start;
1099 
1106 
1113 
1119 
1120 #ifdef STARPU_OPENMP
1121 
1125  struct starpu_omp_task *omp_task;
1126 #else
1127  void *omp_task;
1128 #endif
1129 
1134 
1139  void *sched_data;
1140 };
1141 
1142 #define STARPU_TASK_TYPE_NORMAL 0
1143 #define STARPU_TASK_TYPE_INTERNAL (1<<0)
1144 #define STARPU_TASK_TYPE_DATA_ACQUIRE (1<<1)
1145 
1151 /* Note: remember to update starpu_task_init as well */
1152 #define STARPU_TASK_INITIALIZER \
1153 { \
1154  .cl = NULL, \
1155  .where = -1, \
1156  .cl_arg = NULL, \
1157  .cl_arg_size = 0, \
1158  .callback_func = NULL, \
1159  .callback_arg = NULL, \
1160  .priority = STARPU_DEFAULT_PRIO, \
1161  .use_tag = 0, \
1162  .sequential_consistency = 1, \
1163  .synchronous = 0, \
1164  .execute_on_a_specific_worker = 0, \
1165  .workerorder = 0, \
1166  .bundle = NULL, \
1167  .detach = 1, \
1168  .destroy = 0, \
1169  .regenerate = 0, \
1170  .status = STARPU_TASK_INVALID, \
1171  .profiling_info = NULL, \
1172  .predicted = NAN, \
1173  .predicted_transfer = NAN, \
1174  .predicted_start = NAN, \
1175  .starpu_private = NULL, \
1176  .magic = 42, \
1177  .type = 0, \
1178  .color = 0, \
1179  .sched_ctx = STARPU_NMAX_SCHED_CTXS, \
1180  .hypervisor_tag = 0, \
1181  .flops = 0.0, \
1182  .scheduled = 0, \
1183  .prefetched = 0, \
1184  .dyn_handles = NULL, \
1185  .dyn_interfaces = NULL, \
1186  .dyn_modes = NULL, \
1187  .name = NULL, \
1188  .possibly_parallel = 0 \
1189 }
1190 
1196 #define STARPU_TASK_GET_NBUFFERS(task) ((unsigned)((task)->cl->nbuffers == STARPU_VARIABLE_NBUFFERS ? ((task)->nbuffers) : ((task)->cl->nbuffers)))
1197 
1205 #define STARPU_TASK_GET_HANDLE(task, i) (((task)->dyn_handles) ? (task)->dyn_handles[i] : (task)->handles[i])
1206 #define STARPU_TASK_GET_HANDLES(task) (((task)->dyn_handles) ? (task)->dyn_handles : (task)->handles)
1207 
1215 #define STARPU_TASK_SET_HANDLE(task, handle, i) \
1216  do { if ((task)->dyn_handles) (task)->dyn_handles[i] = handle; else (task)->handles[i] = handle; } while(0)
1217 
1225 #define STARPU_CODELET_GET_MODE(codelet, i) \
1226  (((codelet)->dyn_modes) ? (codelet)->dyn_modes[i] : (assert(i < STARPU_NMAXBUFS), (codelet)->modes[i]))
1227 
1235 #define STARPU_CODELET_SET_MODE(codelet, mode, i) \
1236  do { if ((codelet)->dyn_modes) (codelet)->dyn_modes[i] = mode; else (codelet)->modes[i] = mode; } while(0)
1237 
1245 #define STARPU_TASK_GET_MODE(task, i) \
1246  ((task)->cl->nbuffers == STARPU_VARIABLE_NBUFFERS || (task)->dyn_modes ? \
1247  (((task)->dyn_modes) ? (task)->dyn_modes[i] : (task)->modes[i]) : \
1248  STARPU_CODELET_GET_MODE((task)->cl, i) )
1249 
1257 #define STARPU_TASK_SET_MODE(task, mode, i) \
1258  do { \
1259  if ((task)->cl->nbuffers == STARPU_VARIABLE_NBUFFERS || (task)->cl->nbuffers > STARPU_NMAXBUFS) \
1260  if ((task)->dyn_modes) (task)->dyn_modes[i] = mode; else (task)->modes[i] = mode; \
1261  else \
1262  STARPU_CODELET_SET_MODE((task)->cl, mode, i); \
1263  } while(0)
1264 
1272 #define STARPU_CODELET_GET_NODE(codelet, i) (((codelet)->dyn_nodes) ? (codelet)->dyn_nodes[i] : (codelet)->nodes[i])
1273 
1281 #define STARPU_CODELET_SET_NODE(codelet, __node, i) \
1282  do { if ((codelet)->dyn_nodes) (codelet)->dyn_nodes[i] = __node; else (codelet)->nodes[i] = __node; } while(0)
1283 
1291 void starpu_task_init(struct starpu_task *task);
1292 
1304 void starpu_task_clean(struct starpu_task *task);
1305 
1317 
1326 void starpu_task_destroy(struct starpu_task *task);
1327 
1345 int starpu_task_submit(struct starpu_task *task) STARPU_WARN_UNUSED_RESULT;
1346 
1352 int starpu_task_submit_to_ctx(struct starpu_task *task, unsigned sched_ctx_id);
1353 
1354 int starpu_task_finished(struct starpu_task *task) STARPU_WARN_UNUSED_RESULT;
1355 
1363 int starpu_task_wait(struct starpu_task *task) STARPU_WARN_UNUSED_RESULT;
1364 
1370 int starpu_task_wait_array(struct starpu_task **tasks, unsigned nb_tasks) STARPU_WARN_UNUSED_RESULT;
1371 
1377 int starpu_task_wait_for_all(void);
1378 
1384 int starpu_task_wait_for_n_submitted(unsigned n);
1385 
1390 int starpu_task_wait_for_all_in_ctx(unsigned sched_ctx_id);
1391 
1397 int starpu_task_wait_for_n_submitted_in_ctx(unsigned sched_ctx_id, unsigned n);
1398 
1403 
1409 int starpu_task_nready(void);
1410 
1414 int starpu_task_nsubmitted(void);
1415 
1428 void starpu_iteration_push(unsigned long iteration);
1429 
1435 void starpu_iteration_pop(void);
1436 
1437 void starpu_do_schedule(void);
1438 
1444 void starpu_codelet_init(struct starpu_codelet *cl);
1445 
1450 
1456 struct starpu_task *starpu_task_get_current(void);
1457 
1468 int starpu_task_get_current_data_node(unsigned i);
1469 
1473 const char *starpu_task_get_model_name(struct starpu_task *task);
1474 
1479 const char *starpu_task_get_name(struct starpu_task *task);
1480 
1484 struct starpu_task *starpu_task_dup(struct starpu_task *task);
1485 
1490 void starpu_task_set_implementation(struct starpu_task *task, unsigned impl);
1491 
1496 unsigned starpu_task_get_implementation(struct starpu_task *task);
1497 
1502 void starpu_create_sync_task(starpu_tag_t sync_tag, unsigned ndeps, starpu_tag_t *deps, void (*callback)(void *), void *callback_arg);
1503 
1506 #ifdef __cplusplus
1507 }
1508 #endif
1509 
1510 #endif /* __STARPU_TASK_H__ */
void * prologue_callback_arg
Definition: starpu_task.h:760
unsigned color
Definition: starpu_task.h:522
unsigned use_tag
Definition: starpu_task.h:831
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:902
int max_parallelism
Definition: starpu_task.h:289
int starpu_task_submit_to_ctx(struct starpu_task *task, unsigned sched_ctx_id)
uint32_t * workerids
Definition: starpu_task.h:964
unsigned execute_on_a_specific_worker
Definition: starpu_task.h:863
void(* starpu_opencl_func_t)(void **, void *)
Definition: starpu_task.h:175
int starpu_task_nready(void)
unsigned possibly_parallel
Definition: starpu_task.h:1054
unsigned type
Definition: starpu_task.h:1022
struct starpu_omp_task * omp_task
Definition: starpu_task.h:1125
double predicted
Definition: starpu_task.h:1088
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:995
unsigned workerids_len
Definition: starpu_task.h:972
struct starpu_task * prev
Definition: starpu_task.h:1105
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:842
void starpu_iteration_pop(void)
unsigned workerid
Definition: starpu_task.h:937
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:874
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:1011
struct starpu_profiling_task_info * profiling_info
Definition: starpu_task.h:1067
void starpu_task_clean(struct starpu_task *task)
unsigned sched_ctx
Definition: starpu_task.h:1038
void starpu_task_destroy(struct starpu_task *task)
unsigned nb_termination_call_required
Definition: starpu_task.h:1133
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:909
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:916
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:1112
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:1118
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:1030
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:773
unsigned synchronous
Definition: starpu_task.h:853
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:1139
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:110
void starpu_task_init(struct starpu_task *task)
double predicted_transfer
Definition: starpu_task.h:1097
unsigned cl_arg_free
Definition: starpu_task.h:788
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:819
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:112
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:1080
unsigned destroy
Definition: starpu_task.h:891
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:1060
unsigned callback_arg_free
Definition: starpu_task.h:798
starpu_codelet_type
Definition: starpu_task.h:128
Definition: starpu_task.h:156
#define STARPU_NMAXBUFS
Definition: starpu_config.h:104
void(* starpu_cuda_func_t)(void **, void *)
Definition: starpu_task.h:170
void * callback_arg
Definition: starpu_task.h:735
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:953
int flags
Definition: starpu_task.h:527
unsigned prologue_callback_arg_free
Definition: starpu_task.h:808
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:923
int hypervisor_tag
Definition: starpu_task.h:1046
int starpu_task_wait_for_no_ready(void)