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-2021 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 {
128  STARPU_SEQ = 0,
131  STARPU_SPMD,
143 };
144 
146 {
148 #define STARPU_TASK_INIT 0
149 #define STARPU_TASK_INVALID STARPU_TASK_INIT
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 
535  void (*callback_func)(void *);
536 
540  int flags;
541 
545  int checked;
546 };
547 
552 {
555 };
556 
567 {
575  const char *name;
576 
585 
593  int32_t where;
594 
602  int nbuffers;
603 
604  /* Keep dyn_handles, dyn_interfaces and dyn_modes before the
605  * equivalent static arrays, so we can detect dyn_handles
606  * being NULL while nbuffers being bigger that STARPU_NMAXBUFS
607  * (otherwise the overflow would put a non-NULL) */
608 
648 
684 
694 
709  void *cl_arg;
726  size_t cl_arg_size;
727 
744  void (*callback_func)(void *);
758 
772  void (*prologue_callback_func)(void *);
773 
784 
797  void (*prologue_callback_pop_func)(void *);
808 
818 
832  unsigned cl_arg_free:1;
833 
845  unsigned callback_arg_free:1;
846 
859 
873 
884  unsigned use_tag:1;
885 
897 
907  unsigned synchronous:1;
908 
918 
928  unsigned detach:1;
929 
945  unsigned destroy:1;
946 
956  unsigned regenerate:1;
957 
965  unsigned no_submitorder:1;
966 
972  unsigned char mf_skip;
973 
979  unsigned char scheduled;
980 
986  unsigned char prefetched;
987 
999  unsigned workerid;
1000 
1015  unsigned workerorder;
1016 
1029  uint32_t *workerids;
1030 
1040  unsigned workerids_len;
1041 
1064 
1071 
1079  int magic;
1080 
1090  unsigned type;
1091 
1098  unsigned color;
1099 
1106  unsigned sched_ctx;
1107 
1115 
1123 
1129 
1138 
1151  double flops;
1159  double predicted;
1160 
1169  double predicted_start;
1170 
1177 
1184 
1190 
1191 #ifdef STARPU_OPENMP
1196  struct starpu_omp_task *omp_task;
1197 #else
1198  void *omp_task;
1199 #endif
1205 
1213  void *sched_data;
1214 };
1215 
1219 #define STARPU_TASK_TYPE_NORMAL 0
1220 
1224 #define STARPU_TASK_TYPE_INTERNAL (1<<0)
1225 
1229 #define STARPU_TASK_TYPE_DATA_ACQUIRE (1<<1)
1230 
1236 /* Note: remember to update starpu_task_init as well */
1237 #define STARPU_TASK_INITIALIZER \
1238 { \
1239  .cl = NULL, \
1240  .where = -1, \
1241  .cl_arg = NULL, \
1242  .cl_arg_size = 0, \
1243  .callback_func = NULL, \
1244  .callback_arg = NULL, \
1245  .priority = STARPU_DEFAULT_PRIO, \
1246  .use_tag = 0, \
1247  .sequential_consistency = 1, \
1248  .synchronous = 0, \
1249  .execute_on_a_specific_worker = 0, \
1250  .workerorder = 0, \
1251  .bundle = NULL, \
1252  .detach = 1, \
1253  .destroy = 0, \
1254  .regenerate = 0, \
1255  .status = STARPU_TASK_INIT, \
1256  .profiling_info = NULL, \
1257  .predicted = NAN, \
1258  .predicted_transfer = NAN, \
1259  .predicted_start = NAN, \
1260  .starpu_private = NULL, \
1261  .magic = 42, \
1262  .type = 0, \
1263  .color = 0, \
1264  .sched_ctx = STARPU_NMAX_SCHED_CTXS, \
1265  .hypervisor_tag = 0, \
1266  .flops = 0.0, \
1267  .scheduled = 0, \
1268  .prefetched = 0, \
1269  .dyn_handles = NULL, \
1270  .dyn_interfaces = NULL, \
1271  .dyn_modes = NULL, \
1272  .name = NULL, \
1273  .possibly_parallel = 0 \
1274 }
1275 
1281 #define STARPU_TASK_GET_NBUFFERS(task) ((unsigned)((task)->cl->nbuffers == STARPU_VARIABLE_NBUFFERS ? ((task)->nbuffers) : ((task)->cl->nbuffers)))
1282 
1290 #define STARPU_TASK_GET_HANDLE(task, i) (((task)->dyn_handles) ? (task)->dyn_handles[i] : (task)->handles[i])
1291 #define STARPU_TASK_GET_HANDLES(task) (((task)->dyn_handles) ? (task)->dyn_handles : (task)->handles)
1292 
1300 #define STARPU_TASK_SET_HANDLE(task, handle, i) \
1301  do { if ((task)->dyn_handles) (task)->dyn_handles[i] = handle; else (task)->handles[i] = handle; } while(0)
1302 
1310 #define STARPU_CODELET_GET_MODE(codelet, i) \
1311  (((codelet)->dyn_modes) ? (codelet)->dyn_modes[i] : (assert(i < STARPU_NMAXBUFS), (codelet)->modes[i]))
1312 
1320 #define STARPU_CODELET_SET_MODE(codelet, mode, i) \
1321  do { if ((codelet)->dyn_modes) (codelet)->dyn_modes[i] = mode; else (codelet)->modes[i] = mode; } while(0)
1322 
1330 #define STARPU_TASK_GET_MODE(task, i) \
1331  ((task)->cl->nbuffers == STARPU_VARIABLE_NBUFFERS || (task)->dyn_modes ? \
1332  (((task)->dyn_modes) ? (task)->dyn_modes[i] : (task)->modes[i]) : \
1333  STARPU_CODELET_GET_MODE((task)->cl, i) )
1334 
1342 #define STARPU_TASK_SET_MODE(task, mode, i) \
1343  do { \
1344  if ((task)->cl->nbuffers == STARPU_VARIABLE_NBUFFERS || (task)->cl->nbuffers > STARPU_NMAXBUFS) \
1345  if ((task)->dyn_modes) (task)->dyn_modes[i] = mode; else (task)->modes[i] = mode; \
1346  else \
1347  STARPU_CODELET_SET_MODE((task)->cl, mode, i); \
1348  } while(0)
1349 
1357 #define STARPU_CODELET_GET_NODE(codelet, i) (((codelet)->dyn_nodes) ? (codelet)->dyn_nodes[i] : (codelet)->nodes[i])
1358 
1366 #define STARPU_CODELET_SET_NODE(codelet, __node, i) \
1367  do { if ((codelet)->dyn_nodes) (codelet)->dyn_nodes[i] = __node; else (codelet)->nodes[i] = __node; } while(0)
1368 
1376 void starpu_task_init(struct starpu_task *task);
1377 
1389 void starpu_task_clean(struct starpu_task *task);
1390 
1402 
1412 
1430 int starpu_task_submit(struct starpu_task *task) STARPU_WARN_UNUSED_RESULT;
1431 
1437 int starpu_task_submit_to_ctx(struct starpu_task *task, unsigned sched_ctx_id);
1438 
1439 int starpu_task_finished(struct starpu_task *task) STARPU_WARN_UNUSED_RESULT;
1440 
1448 int starpu_task_wait(struct starpu_task *task) STARPU_WARN_UNUSED_RESULT;
1449 
1455 int starpu_task_wait_array(struct starpu_task **tasks, unsigned nb_tasks) STARPU_WARN_UNUSED_RESULT;
1456 
1463 
1470 
1475 int starpu_task_wait_for_all_in_ctx(unsigned sched_ctx_id);
1476 
1482 int starpu_task_wait_for_n_submitted_in_ctx(unsigned sched_ctx_id, unsigned n);
1483 
1488 
1495 
1500 
1513 void starpu_iteration_push(unsigned long iteration);
1514 
1521 
1522 void starpu_do_schedule(void);
1523 
1530 
1535 
1542 
1554 
1558 const char *starpu_task_get_model_name(struct starpu_task *task);
1559 
1564 const char *starpu_task_get_name(struct starpu_task *task);
1565 
1570 
1575 void starpu_task_set_implementation(struct starpu_task *task, unsigned impl);
1576 
1582 
1587 void starpu_create_sync_task(starpu_tag_t sync_tag, unsigned ndeps, starpu_tag_t *deps, void (*callback)(void *), void *callback_arg);
1588 
1592 void starpu_create_callback_task(void (*callback)(void *), void *callback_arg);
1593 
1598 void starpu_task_watchdog_set_hook(void (*hook)(void *), void *hook_arg);
1599 
1602 #ifdef __cplusplus
1603 }
1604 #endif
1605 
1606 #endif /* __STARPU_TASK_H__ */
starpu_task_bundle_t bundle
Definition: starpu_task.h:1128
starpu_mpi_ms_func_t mpi_ms_funcs[STARPU_MAXIMPLEMENTATIONS]
Definition: starpu_task.h:401
unsigned specific_nodes
Definition: starpu_task.h:460
void(* callback_func)(void *)
Definition: starpu_task.h:744
int max_parallelism
Definition: starpu_task.h:288
unsigned sched_ctx
Definition: starpu_task.h:1106
unsigned nb_termination_call_required
Definition: starpu_task.h:1204
unsigned synchronous
Definition: starpu_task.h:907
int checked
Definition: starpu_task.h:545
int nbuffers
Definition: starpu_task.h:425
void * cl_arg
Definition: starpu_task.h:709
starpu_opencl_func_t opencl_func
Definition: starpu_task.h:309
double predicted_transfer
Definition: starpu_task.h:1168
struct starpu_perfmodel * model
Definition: starpu_task.h:490
unsigned long per_worker_stats[STARPU_NMAXWORKERS]
Definition: starpu_task.h:509
int(* can_execute)(unsigned workerid, struct starpu_task *task, unsigned nimpl)
Definition: starpu_task.h:272
char opencl_flags[STARPU_MAXIMPLEMENTATIONS]
Definition: starpu_task.h:369
unsigned use_tag
Definition: starpu_task.h:884
unsigned callback_arg_free
Definition: starpu_task.h:845
starpu_cuda_func_t cuda_func
Definition: starpu_task.h:302
unsigned cl_arg_free
Definition: starpu_task.h:832
unsigned destroy
Definition: starpu_task.h:945
int * dyn_nodes
Definition: starpu_task.h:482
enum starpu_data_access_mode modes[STARPU_NMAXBUFS]
Definition: starpu_task.h:683
starpu_mic_func_t mic_funcs[STARPU_MAXIMPLEMENTATIONS]
Definition: starpu_task.h:385
void * prologue_callback_arg
Definition: starpu_task.h:783
int hypervisor_tag
Definition: starpu_task.h:1114
int32_t where
Definition: starpu_task.h:593
uint32_t where
Definition: starpu_task.h:265
void(* callback_func)(void *)
Definition: starpu_task.h:535
unsigned execute_on_a_specific_worker
Definition: starpu_task.h:917
starpu_data_handle_t * dyn_handles
Definition: starpu_task.h:622
starpu_cpu_func_t cpu_funcs[STARPU_MAXIMPLEMENTATIONS]
Definition: starpu_task.h:326
void * starpu_private
Definition: starpu_task.h:1189
unsigned type
Definition: starpu_task.h:1090
unsigned prologue_callback_arg_free
Definition: starpu_task.h:858
enum starpu_data_access_mode modes[STARPU_NMAXBUFS]
Definition: starpu_task.h:436
unsigned workerid
Definition: starpu_task.h:999
unsigned char mf_skip
Definition: starpu_task.h:972
unsigned workerorder
Definition: starpu_task.h:1015
enum starpu_task_status status
Definition: starpu_task.h:1070
starpu_opencl_func_t opencl_funcs[STARPU_MAXIMPLEMENTATIONS]
Definition: starpu_task.h:362
unsigned workerids_len
Definition: starpu_task.h:1040
struct starpu_profiling_task_info * profiling_info
Definition: starpu_task.h:1137
const char * name
Definition: starpu_task.h:575
double flops
Definition: starpu_task.h:1151
starpu_tag_t tag_id
Definition: starpu_task.h:817
void * prologue_callback_pop_arg
Definition: starpu_task.h:807
void ** dyn_interfaces
Definition: starpu_task.h:630
unsigned possibly_parallel
Definition: starpu_task.h:1122
double predicted
Definition: starpu_task.h:1159
unsigned char * handles_sequential_consistency
Definition: starpu_task.h:693
unsigned char prefetched
Definition: starpu_task.h:986
unsigned detach
Definition: starpu_task.h:928
int priority
Definition: starpu_task.h:1063
unsigned char scheduled
Definition: starpu_task.h:979
enum starpu_data_access_mode * dyn_modes
Definition: starpu_task.h:449
void * callback_arg
Definition: starpu_task.h:757
starpu_cuda_func_t cuda_funcs[STARPU_MAXIMPLEMENTATIONS]
Definition: starpu_task.h:341
int nbuffers
Definition: starpu_task.h:602
char cuda_flags[STARPU_MAXIMPLEMENTATIONS]
Definition: starpu_task.h:348
struct starpu_omp_task * omp_task
Definition: starpu_task.h:1196
enum starpu_data_access_mode mode
Definition: starpu_task.h:554
int nodes[STARPU_NMAXBUFS]
Definition: starpu_task.h:469
unsigned color
Definition: starpu_task.h:1098
const char * cpu_funcs_name[STARPU_MAXIMPLEMENTATIONS]
Definition: starpu_task.h:410
struct starpu_codelet * cl
Definition: starpu_task.h:584
int magic
Definition: starpu_task.h:1079
starpu_data_handle_t handle
Definition: starpu_task.h:553
uint32_t * workerids
Definition: starpu_task.h:1029
int flags
Definition: starpu_task.h:540
void(* prologue_callback_pop_func)(void *)
Definition: starpu_task.h:797
starpu_cpu_func_t cpu_func
Definition: starpu_task.h:295
unsigned color
Definition: starpu_task.h:521
size_t cl_arg_size
Definition: starpu_task.h:726
void * sched_data
Definition: starpu_task.h:1213
const char * name
Definition: starpu_task.h:515
struct starpu_task * prev
Definition: starpu_task.h:1176
struct starpu_task * next
Definition: starpu_task.h:1183
void(* prologue_callback_func)(void *)
Definition: starpu_task.h:772
enum starpu_data_access_mode * dyn_modes
Definition: starpu_task.h:647
unsigned sequential_consistency
Definition: starpu_task.h:896
unsigned prologue_callback_pop_arg_free
Definition: starpu_task.h:872
unsigned regenerate
Definition: starpu_task.h:956
starpu_data_handle_t handles[STARPU_NMAXBUFS]
Definition: starpu_task.h:661
enum starpu_codelet_type type
Definition: starpu_task.h:281
unsigned no_submitorder
Definition: starpu_task.h:965
struct starpu_perfmodel * energy_model
Definition: starpu_task.h:500
void * interfaces[STARPU_NMAXBUFS]
Definition: starpu_task.h:668
starpu_task_status
Definition: starpu_task.h:146
const char * starpu_task_get_model_name(struct starpu_task *task)
struct starpu_task * starpu_task_create(void) STARPU_ATTRIBUTE_MALLOC
void(* starpu_cuda_func_t)(void **, void *)
Definition: starpu_task.h:169
void starpu_codelet_display_stats(struct starpu_codelet *cl)
int starpu_task_nready(void)
void(* starpu_cpu_func_t)(void **, void *)
Definition: starpu_task.h:164
struct starpu_task * starpu_task_get_current(void)
void(* starpu_mpi_ms_kernel_t)(void **, void *)
Definition: starpu_task.h:189
const char * starpu_task_get_name(struct starpu_task *task)
int starpu_task_submit_to_ctx(struct starpu_task *task, unsigned sched_ctx_id)
starpu_mpi_ms_kernel_t(* starpu_mpi_ms_func_t)(void)
Definition: starpu_task.h:194
struct starpu_task * starpu_task_dup(struct starpu_task *task)
void starpu_codelet_init(struct starpu_codelet *cl)
int starpu_task_wait_for_no_ready(void)
starpu_mic_kernel_t(* starpu_mic_func_t)(void)
Definition: starpu_task.h:184
void(* starpu_opencl_func_t)(void **, void *)
Definition: starpu_task.h:174
int starpu_task_wait_for_n_submitted(unsigned n)
void starpu_iteration_pop(void)
void starpu_create_sync_task(starpu_tag_t sync_tag, unsigned ndeps, starpu_tag_t *deps, void(*callback)(void *), void *callback_arg)
int starpu_task_get_current_data_node(unsigned i)
void starpu_task_destroy(struct starpu_task *task)
void(* starpu_mic_kernel_t)(void **, void *)
Definition: starpu_task.h:179
void starpu_task_watchdog_set_hook(void(*hook)(void *), void *hook_arg)
void starpu_create_callback_task(void(*callback)(void *), void *callback_arg)
int starpu_task_submit(struct starpu_task *task) STARPU_WARN_UNUSED_RESULT
int starpu_task_wait_array(struct starpu_task **tasks, unsigned nb_tasks) STARPU_WARN_UNUSED_RESULT
void starpu_task_set_implementation(struct starpu_task *task, unsigned impl)
unsigned starpu_task_get_implementation(struct starpu_task *task)
int starpu_task_wait_for_n_submitted_in_ctx(unsigned sched_ctx_id, unsigned n)
starpu_codelet_type
Definition: starpu_task.h:127
int starpu_task_wait_for_all(void)
void starpu_iteration_push(unsigned long iteration)
int starpu_task_wait(struct starpu_task *task) STARPU_WARN_UNUSED_RESULT
#define STARPU_NMAXBUFS
Definition: starpu_config.h:194
void starpu_task_init(struct starpu_task *task)
int starpu_task_nsubmitted(void)
void starpu_task_clean(struct starpu_task *task)
int starpu_task_wait_for_all_in_ctx(unsigned sched_ctx_id)
@ STARPU_TASK_BLOCKED_ON_DATA
Definition: starpu_task.h:157
@ STARPU_TASK_READY
Definition: starpu_task.h:152
@ STARPU_TASK_BLOCKED_ON_TAG
Definition: starpu_task.h:155
@ STARPU_TASK_STOPPED
Definition: starpu_task.h:158
@ STARPU_TASK_INIT
Definition: starpu_task.h:147
@ STARPU_TASK_BLOCKED_ON_TASK
Definition: starpu_task.h:156
@ STARPU_TASK_RUNNING
Definition: starpu_task.h:153
@ STARPU_TASK_BLOCKED
Definition: starpu_task.h:150
@ STARPU_TASK_FINISHED
Definition: starpu_task.h:154
@ STARPU_FORKJOIN
Definition: starpu_task.h:137
@ STARPU_SPMD
Definition: starpu_task.h:131
@ STARPU_SEQ
Definition: starpu_task.h:128
Definition: starpu_task.h:250
Definition: starpu_task.h:552
Definition: starpu_task.h:567
starpu_data_access_mode
Definition: starpu_data.h:55
struct _starpu_data_state * starpu_data_handle_t
Definition: starpu_data.h:44
uint64_t starpu_tag_t
Definition: starpu_task_dep.h:127
Definition: starpu_perfmodel.h:189
Definition: starpu_profiling.h:49
#define STARPU_MAXIMPLEMENTATIONS
Definition: starpu_config.h:252
struct _starpu_task_bundle * starpu_task_bundle_t
Definition: starpu_task_bundle.h:40
#define STARPU_ATTRIBUTE_MALLOC
Definition: starpu_util.h:112
#define STARPU_NMAXWORKERS
Definition: starpu_config.h:236