StarPU Handbook
starpu_task.h
Go to the documentation of this file.
1 /* StarPU --- Runtime system for heterogeneous multicore architectures.
2  *
3  * Copyright (C) 2009-2020 Université de Bordeaux, CNRS (LaBRI UMR 5800), Inria
4  * Copyright (C) 2011 Télécom-SudParis
5  * Copyright (C) 2016 Uppsala University
6  *
7  * StarPU is free software; you can redistribute it and/or modify
8  * it under the terms of the GNU Lesser General Public License as published by
9  * the Free Software Foundation; either version 2.1 of the License, or (at
10  * your option) any later version.
11  *
12  * StarPU is distributed in the hope that it will be useful, but
13  * WITHOUT ANY WARRANTY; without even the implied warranty of
14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
15  *
16  * See the GNU Lesser General Public License in COPYING.LGPL for more details.
17  */
18 
19 #ifndef __STARPU_TASK_H__
20 #define __STARPU_TASK_H__
21 
22 #include <starpu.h>
23 #include <errno.h>
24 #include <assert.h>
25 
26 #if defined STARPU_USE_CUDA && !defined STARPU_DONT_INCLUDE_CUDA_HEADERS
27 # include <cuda.h>
28 #endif
29 
30 #ifdef __cplusplus
31 extern "C"
32 {
33 #endif
34 
48 #define STARPU_NOWHERE ((1ULL)<<0)
49 
55 #define STARPU_CPU ((1ULL)<<1)
56 
62 #define STARPU_CUDA ((1ULL)<<3)
63 
69 #define STARPU_OPENCL ((1ULL)<<6)
70 
76 #define STARPU_MIC ((1ULL)<<7)
77 
83 #define STARPU_MPI_MS ((1ULL)<<9)
84 
89 #define STARPU_CODELET_SIMGRID_EXECUTE (1<<0)
90 
96 #define STARPU_CODELET_SIMGRID_EXECUTE_AND_INJECT (1<<1)
97 
102 #define STARPU_CODELET_NOPLANS (1<<2)
103 
108 #define STARPU_CUDA_ASYNC (1<<0)
109 
114 #define STARPU_OPENCL_ASYNC (1<<0)
115 
119 #define STARPU_MAIN_RAM 0
120 
121 
127 {
143 };
144 
146 {
148 #define STARPU_TASK_INIT 0
149 #define STARPU_TASK_INVALID STARPU_TASK_INIT
150  STARPU_TASK_BLOCKED,
152  STARPU_TASK_READY,
153  STARPU_TASK_RUNNING,
154  STARPU_TASK_FINISHED,
155  STARPU_TASK_BLOCKED_ON_TAG,
156  STARPU_TASK_BLOCKED_ON_TASK,
157  STARPU_TASK_BLOCKED_ON_DATA,
158  STARPU_TASK_STOPPED
159 };
160 
164 typedef void (*starpu_cpu_func_t)(void **, void*);
165 
169 typedef void (*starpu_cuda_func_t)(void **, void*);
170 
174 typedef void (*starpu_opencl_func_t)(void **, void*);
175 
179 typedef void (*starpu_mic_kernel_t)(void **, void*);
180 
185 
189 typedef void (*starpu_mpi_ms_kernel_t)(void **, void*);
190 
195 
203 #define STARPU_MULTIPLE_CPU_IMPLEMENTATIONS ((starpu_cpu_func_t) -1)
204 
212 #define STARPU_MULTIPLE_CUDA_IMPLEMENTATIONS ((starpu_cuda_func_t) -1)
213 
221 #define STARPU_MULTIPLE_OPENCL_IMPLEMENTATIONS ((starpu_opencl_func_t) -1)
222 
228 #define STARPU_VARIABLE_NBUFFERS (-1)
229 
235 #define STARPU_SPECIFIC_NODE_LOCAL (-1)
236 #define STARPU_SPECIFIC_NODE_CPU (-2)
237 #define STARPU_SPECIFIC_NODE_SLOW (-3)
238 #define STARPU_SPECIFIC_NODE_FAST (-4)
239 
240 struct starpu_task;
241 
250 {
265  uint32_t where;
266 
272  int (*can_execute)(unsigned workerid, struct starpu_task *task, unsigned nimpl);
273 
282 
289 
295  starpu_cpu_func_t cpu_func STARPU_DEPRECATED;
296 
302  starpu_cuda_func_t cuda_func STARPU_DEPRECATED;
303 
310 
327 
342 
349 
363 
370 
386 
402 
411 
425  int nbuffers;
426 
437 
450 
460  unsigned specific_nodes;
461 
470 
482  int *dyn_nodes;
483 
491 
501 
510 
515  const char *name;
516 
521  unsigned color;
522 
526  int flags;
527 
531  int checked;
532 };
533 
538 {
541 };
542 
553 {
561  const char *name;
562 
571 
579  int32_t where;
580 
588  int nbuffers;
589 
590  /* Keep dyn_handles, dyn_interfaces and dyn_modes before the
591  * equivalent static arrays, so we can detect dyn_handles
592  * being NULL while nbuffers being bigger that STARPU_NMAXBUFS
593  * (otherwise the overflow would put a non-NULL) */
594 
634 
654  void *interfaces[STARPU_NMAXBUFS];
670 
680 
695  void *cl_arg;
712  size_t cl_arg_size;
713 
730  void (*callback_func)(void *);
744 
758  void (*prologue_callback_func)(void *);
759 
770 
771  void (*prologue_callback_pop_func)(void *);
772  void *prologue_callback_pop_arg;
773 
783 
797  unsigned cl_arg_free:1;
798 
810  unsigned callback_arg_free:1;
811 
824 
838 
849  unsigned use_tag:1;
850 
862 
872  unsigned synchronous:1;
873 
883 
893  unsigned detach:1;
894 
910  unsigned destroy:1;
911 
921  unsigned regenerate:1;
922 
928  unsigned mf_skip:1;
929 
937  unsigned no_submitorder:1;
938 
944  unsigned scheduled:1;
945  unsigned prefetched:1;
946 
958  unsigned workerid;
959 
974  unsigned workerorder;
975 
988  uint32_t *workerids;
989 
999  unsigned workerids_len;
1000 
1023 
1029  enum starpu_task_status status;
1030 
1038  int magic;
1039 
1049  unsigned type;
1050 
1057  unsigned color;
1058 
1065  unsigned sched_ctx;
1066 
1074 
1082 
1088 
1097 
1109  double flops;
1117  double predicted;
1118 
1127  double predicted_start;
1128 
1135 
1142 
1148 
1149 #ifdef STARPU_OPENMP
1150 
1154  struct starpu_omp_task *omp_task;
1155 #else
1156  void *omp_task;
1157 #endif
1158 
1163 
1171  void *sched_data;
1172 };
1173 
1177 #define STARPU_TASK_TYPE_NORMAL 0
1178 
1182 #define STARPU_TASK_TYPE_INTERNAL (1<<0)
1183 
1187 #define STARPU_TASK_TYPE_DATA_ACQUIRE (1<<1)
1188 
1194 /* Note: remember to update starpu_task_init as well */
1195 #define STARPU_TASK_INITIALIZER \
1196 { \
1197  .cl = NULL, \
1198  .where = -1, \
1199  .cl_arg = NULL, \
1200  .cl_arg_size = 0, \
1201  .callback_func = NULL, \
1202  .callback_arg = NULL, \
1203  .priority = STARPU_DEFAULT_PRIO, \
1204  .use_tag = 0, \
1205  .sequential_consistency = 1, \
1206  .synchronous = 0, \
1207  .execute_on_a_specific_worker = 0, \
1208  .workerorder = 0, \
1209  .bundle = NULL, \
1210  .detach = 1, \
1211  .destroy = 0, \
1212  .regenerate = 0, \
1213  .status = STARPU_TASK_INIT, \
1214  .profiling_info = NULL, \
1215  .predicted = NAN, \
1216  .predicted_transfer = NAN, \
1217  .predicted_start = NAN, \
1218  .starpu_private = NULL, \
1219  .magic = 42, \
1220  .type = 0, \
1221  .color = 0, \
1222  .sched_ctx = STARPU_NMAX_SCHED_CTXS, \
1223  .hypervisor_tag = 0, \
1224  .flops = 0.0, \
1225  .scheduled = 0, \
1226  .prefetched = 0, \
1227  .dyn_handles = NULL, \
1228  .dyn_interfaces = NULL, \
1229  .dyn_modes = NULL, \
1230  .name = NULL, \
1231  .possibly_parallel = 0 \
1232 }
1233 
1239 #define STARPU_TASK_GET_NBUFFERS(task) ((unsigned)((task)->cl->nbuffers == STARPU_VARIABLE_NBUFFERS ? ((task)->nbuffers) : ((task)->cl->nbuffers)))
1240 
1248 #define STARPU_TASK_GET_HANDLE(task, i) (((task)->dyn_handles) ? (task)->dyn_handles[i] : (task)->handles[i])
1249 #define STARPU_TASK_GET_HANDLES(task) (((task)->dyn_handles) ? (task)->dyn_handles : (task)->handles)
1250 
1258 #define STARPU_TASK_SET_HANDLE(task, handle, i) \
1259  do { if ((task)->dyn_handles) (task)->dyn_handles[i] = handle; else (task)->handles[i] = handle; } while(0)
1260 
1268 #define STARPU_CODELET_GET_MODE(codelet, i) \
1269  (((codelet)->dyn_modes) ? (codelet)->dyn_modes[i] : (assert(i < STARPU_NMAXBUFS), (codelet)->modes[i]))
1270 
1278 #define STARPU_CODELET_SET_MODE(codelet, mode, i) \
1279  do { if ((codelet)->dyn_modes) (codelet)->dyn_modes[i] = mode; else (codelet)->modes[i] = mode; } while(0)
1280 
1288 #define STARPU_TASK_GET_MODE(task, i) \
1289  ((task)->cl->nbuffers == STARPU_VARIABLE_NBUFFERS || (task)->dyn_modes ? \
1290  (((task)->dyn_modes) ? (task)->dyn_modes[i] : (task)->modes[i]) : \
1291  STARPU_CODELET_GET_MODE((task)->cl, i) )
1292 
1300 #define STARPU_TASK_SET_MODE(task, mode, i) \
1301  do { \
1302  if ((task)->cl->nbuffers == STARPU_VARIABLE_NBUFFERS || (task)->cl->nbuffers > STARPU_NMAXBUFS) \
1303  if ((task)->dyn_modes) (task)->dyn_modes[i] = mode; else (task)->modes[i] = mode; \
1304  else \
1305  STARPU_CODELET_SET_MODE((task)->cl, mode, i); \
1306  } while(0)
1307 
1315 #define STARPU_CODELET_GET_NODE(codelet, i) (((codelet)->dyn_nodes) ? (codelet)->dyn_nodes[i] : (codelet)->nodes[i])
1316 
1324 #define STARPU_CODELET_SET_NODE(codelet, __node, i) \
1325  do { if ((codelet)->dyn_nodes) (codelet)->dyn_nodes[i] = __node; else (codelet)->nodes[i] = __node; } while(0)
1326 
1334 void starpu_task_init(struct starpu_task *task);
1335 
1347 void starpu_task_clean(struct starpu_task *task);
1348 
1360 
1369 void starpu_task_destroy(struct starpu_task *task);
1370 
1388 int starpu_task_submit(struct starpu_task *task) STARPU_WARN_UNUSED_RESULT;
1389 
1395 int starpu_task_submit_to_ctx(struct starpu_task *task, unsigned sched_ctx_id);
1396 
1397 int starpu_task_finished(struct starpu_task *task) STARPU_WARN_UNUSED_RESULT;
1398 
1406 int starpu_task_wait(struct starpu_task *task) STARPU_WARN_UNUSED_RESULT;
1407 
1413 int starpu_task_wait_array(struct starpu_task **tasks, unsigned nb_tasks) STARPU_WARN_UNUSED_RESULT;
1414 
1420 int starpu_task_wait_for_all(void);
1421 
1427 int starpu_task_wait_for_n_submitted(unsigned n);
1428 
1433 int starpu_task_wait_for_all_in_ctx(unsigned sched_ctx_id);
1434 
1440 int starpu_task_wait_for_n_submitted_in_ctx(unsigned sched_ctx_id, unsigned n);
1441 
1446 
1452 int starpu_task_nready(void);
1453 
1457 int starpu_task_nsubmitted(void);
1458 
1471 void starpu_iteration_push(unsigned long iteration);
1472 
1478 void starpu_iteration_pop(void);
1479 
1480 void starpu_do_schedule(void);
1481 
1487 void starpu_codelet_init(struct starpu_codelet *cl);
1488 
1493 
1499 struct starpu_task *starpu_task_get_current(void);
1500 
1511 int starpu_task_get_current_data_node(unsigned i);
1512 
1516 const char *starpu_task_get_model_name(struct starpu_task *task);
1517 
1522 const char *starpu_task_get_name(struct starpu_task *task);
1523 
1527 struct starpu_task *starpu_task_dup(struct starpu_task *task);
1528 
1533 void starpu_task_set_implementation(struct starpu_task *task, unsigned impl);
1534 
1539 unsigned starpu_task_get_implementation(struct starpu_task *task);
1540 
1545 void starpu_create_sync_task(starpu_tag_t sync_tag, unsigned ndeps, starpu_tag_t *deps, void (*callback)(void *), void *callback_arg);
1546 
1550 void starpu_create_callback_task(void (*callback)(void *), void *callback_arg);
1551 
1556 void starpu_task_watchdog_set_hook(void (*hook)(void *), void *hook_arg);
1557 
1560 #ifdef __cplusplus
1561 }
1562 #endif
1563 
1564 #endif /* __STARPU_TASK_H__ */
void * prologue_callback_arg
Definition: starpu_task.h:769
unsigned color
Definition: starpu_task.h:521
unsigned use_tag
Definition: starpu_task.h:849
starpu_opencl_func_t opencl_func
Definition: starpu_task.h:309
char cuda_flags[STARPU_MAXIMPLEMENTATIONS]
Definition: starpu_task.h:348
Definition: starpu_task.h:249
starpu_opencl_func_t opencl_funcs[STARPU_MAXIMPLEMENTATIONS]
Definition: starpu_task.h:362
Definition: starpu_task.h:131
Definition: starpu_profiling.h:48
enum starpu_data_access_mode modes[STARPU_NMAXBUFS]
Definition: starpu_task.h:436
int nbuffers
Definition: starpu_task.h:588
void ** dyn_interfaces
Definition: starpu_task.h:616
void(* starpu_cpu_func_t)(void **, void *)
Definition: starpu_task.h:164
unsigned regenerate
Definition: starpu_task.h:921
int max_parallelism
Definition: starpu_task.h:288
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:988
unsigned execute_on_a_specific_worker
Definition: starpu_task.h:882
void(* starpu_opencl_func_t)(void **, void *)
Definition: starpu_task.h:174
int starpu_task_nready(void)
unsigned possibly_parallel
Definition: starpu_task.h:1081
unsigned type
Definition: starpu_task.h:1049
struct starpu_omp_task * omp_task
Definition: starpu_task.h:1154
double predicted
Definition: starpu_task.h:1117
Definition: starpu_task.h:147
starpu_mic_func_t mic_funcs[STARPU_MAXIMPLEMENTATIONS]
Definition: starpu_task.h:385
#define STARPU_ATTRIBUTE_MALLOC
Definition: starpu_util.h:112
int priority
Definition: starpu_task.h:1022
unsigned workerids_len
Definition: starpu_task.h:999
struct starpu_task * prev
Definition: starpu_task.h:1134
int starpu_task_submit(struct starpu_task *task) STARPU_WARN_UNUSED_RESULT
Definition: starpu_task.h:128
char opencl_flags[STARPU_MAXIMPLEMENTATIONS]
Definition: starpu_task.h:369
int starpu_task_nsubmitted(void)
struct _starpu_task_bundle * starpu_task_bundle_t
Definition: starpu_task_bundle.h:40
unsigned sequential_consistency
Definition: starpu_task.h:861
void starpu_iteration_pop(void)
unsigned workerid
Definition: starpu_task.h:958
const char * starpu_task_get_name(struct starpu_task *task)
size_t cl_arg_size
Definition: starpu_task.h:712
unsigned detach
Definition: starpu_task.h:893
int nodes[STARPU_NMAXBUFS]
Definition: starpu_task.h:469
const char * cpu_funcs_name[STARPU_MAXIMPLEMENTATIONS]
Definition: starpu_task.h:410
int magic
Definition: starpu_task.h:1038
struct starpu_profiling_task_info * profiling_info
Definition: starpu_task.h:1096
void starpu_task_clean(struct starpu_task *task)
unsigned sched_ctx
Definition: starpu_task.h:1065
void starpu_task_destroy(struct starpu_task *task)
unsigned nb_termination_call_required
Definition: starpu_task.h:1162
int starpu_task_wait_for_all(void)
starpu_cpu_func_t cpu_func
Definition: starpu_task.h:295
unsigned specific_nodes
Definition: starpu_task.h:460
void(* starpu_mpi_ms_kernel_t)(void **, void *)
Definition: starpu_task.h:189
void * cl_arg
Definition: starpu_task.h:695
starpu_data_handle_t * dyn_handles
Definition: starpu_task.h:608
uint32_t where
Definition: starpu_task.h:265
Definition: starpu_task.h:137
unsigned mf_skip
Definition: starpu_task.h:928
starpu_mpi_ms_func_t mpi_ms_funcs[STARPU_MAXIMPLEMENTATIONS]
Definition: starpu_task.h:401
unsigned no_submitorder
Definition: starpu_task.h:937
struct starpu_perfmodel * model
Definition: starpu_task.h:490
int starpu_task_wait_array(struct starpu_task **tasks, unsigned nb_tasks) STARPU_WARN_UNUSED_RESULT
struct starpu_task * next
Definition: starpu_task.h:1141
enum starpu_codelet_type type
Definition: starpu_task.h:281
starpu_cuda_func_t cuda_funcs[STARPU_MAXIMPLEMENTATIONS]
Definition: starpu_task.h:341
void * starpu_private
Definition: starpu_task.h:1147
starpu_mic_kernel_t(* starpu_mic_func_t)(void)
Definition: starpu_task.h:184
void(* starpu_mic_kernel_t)(void **, void *)
Definition: starpu_task.h:179
uint64_t starpu_tag_t
Definition: starpu_task_dep.h:127
struct starpu_task * starpu_task_dup(struct starpu_task *task)
unsigned color
Definition: starpu_task.h:1057
const char * name
Definition: starpu_task.h:515
int starpu_task_wait_for_all_in_ctx(unsigned sched_ctx_id)
Definition: starpu_task.h:552
starpu_task_status
Definition: starpu_task.h:145
starpu_mpi_ms_kernel_t(* starpu_mpi_ms_func_t)(void)
Definition: starpu_task.h:194
const char * name
Definition: starpu_task.h:561
void starpu_iteration_push(unsigned long iteration)
starpu_tag_t tag_id
Definition: starpu_task.h:782
unsigned synchronous
Definition: starpu_task.h:872
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:1171
int checked
Definition: starpu_task.h:531
int starpu_task_wait(struct starpu_task *task) STARPU_WARN_UNUSED_RESULT
enum starpu_data_access_mode * dyn_modes
Definition: starpu_task.h:633
int * dyn_nodes
Definition: starpu_task.h:482
struct _starpu_data_state * starpu_data_handle_t
Definition: starpu_data.h:44
#define STARPU_NMAXWORKERS
Definition: starpu_config.h:226
void starpu_task_init(struct starpu_task *task)
double predicted_transfer
Definition: starpu_task.h:1126
unsigned cl_arg_free
Definition: starpu_task.h:797
void starpu_codelet_init(struct starpu_codelet *cl)
unsigned prologue_callback_pop_arg_free
Definition: starpu_task.h:837
int32_t where
Definition: starpu_task.h:579
unsigned char * handles_sequential_consistency
Definition: starpu_task.h:679
void starpu_task_watchdog_set_hook(void(*hook)(void *), void *hook_arg)
struct starpu_task * starpu_task_create(void) STARPU_ATTRIBUTE_MALLOC
#define STARPU_MAXIMPLEMENTATIONS
Definition: starpu_config.h:242
Definition: starpu_perfmodel.h:188
const char * starpu_task_get_model_name(struct starpu_task *task)
unsigned long per_worker_stats[STARPU_NMAXWORKERS]
Definition: starpu_task.h:509
int nbuffers
Definition: starpu_task.h:425
int starpu_task_wait_for_n_submitted_in_ctx(unsigned sched_ctx_id, unsigned n)
struct starpu_perfmodel * energy_model
Definition: starpu_task.h:500
int(* can_execute)(unsigned workerid, struct starpu_task *task, unsigned nimpl)
Definition: starpu_task.h:272
enum starpu_data_access_mode * dyn_modes
Definition: starpu_task.h:449
starpu_data_access_mode
Definition: starpu_data.h:54
double flops
Definition: starpu_task.h:1109
unsigned destroy
Definition: starpu_task.h:910
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:1087
unsigned callback_arg_free
Definition: starpu_task.h:810
starpu_codelet_type
Definition: starpu_task.h:126
#define STARPU_NMAXBUFS
Definition: starpu_config.h:184
void(* starpu_cuda_func_t)(void **, void *)
Definition: starpu_task.h:169
void * callback_arg
Definition: starpu_task.h:743
starpu_cuda_func_t cuda_func
Definition: starpu_task.h:302
Definition: starpu_task.h:537
unsigned workerorder
Definition: starpu_task.h:974
int flags
Definition: starpu_task.h:526
unsigned prologue_callback_arg_free
Definition: starpu_task.h:823
starpu_cpu_func_t cpu_funcs[STARPU_MAXIMPLEMENTATIONS]
Definition: starpu_task.h:326
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:539
struct starpu_codelet * cl
Definition: starpu_task.h:570
unsigned scheduled
Definition: starpu_task.h:944
int hypervisor_tag
Definition: starpu_task.h:1073
int starpu_task_wait_for_no_ready(void)