Loading...
Searching...
No Matches
Codelet And Tasks

API to manipulate codelets and tasks. More...

## Data Structures

struct | starpu_codelet
struct | starpu_data_descr
struct | starpu_task

## Macros

#define | STARPU_NMAXBUFS
#define | STARPU_NOWHERE
#define | STARPU_WORKER_TO_MASK(worker_archtype)
#define | STARPU_CPU
#define | STARPU_CUDA
#define | STARPU_HIP
#define | STARPU_OPENCL
#define | STARPU_MAX_FPGA
#define | STARPU_MPI_MS
#define | STARPU_TCPIP_MS
#define | STARPU_CODELET_SIMGRID_EXECUTE
#define | STARPU_CODELET_SIMGRID_EXECUTE_AND_INJECT
#define | STARPU_CODELET_NOPLANS
#define | STARPU_CUDA_ASYNC
#define | STARPU_HIP_ASYNC
#define | STARPU_OPENCL_ASYNC
#define | STARPU_MAIN_RAM
#define | STARPU_MULTIPLE_CPU_IMPLEMENTATIONS
#define | STARPU_MULTIPLE_CUDA_IMPLEMENTATIONS
#define | STARPU_MULTIPLE_HIP_IMPLEMENTATIONS
#define | STARPU_MULTIPLE_OPENCL_IMPLEMENTATIONS
#define | STARPU_VARIABLE_NBUFFERS
#define | STARPU_SPECIFIC_NODE_LOCAL
#define | STARPU_SPECIFIC_NODE_CPU
#define | STARPU_SPECIFIC_NODE_SLOW
#define | STARPU_SPECIFIC_NODE_FAST
#define | STARPU_SPECIFIC_NODE_LOCAL_OR_CPU
#define | STARPU_SPECIFIC_NODE_NONE
#define | STARPU_TASK_TYPE_NORMAL
#define | STARPU_TASK_TYPE_INTERNAL
#define | STARPU_TASK_TYPE_DATA_ACQUIRE
#define | STARPU_TASK_INITIALIZER
#define | STARPU_TASK_GET_NBUFFERS(task)
#define | STARPU_TASK_GET_HANDLE(task, i)
#define | STARPU_TASK_GET_HANDLES(task)
#define | STARPU_TASK_SET_HANDLE(task, handle, i)
#define | STARPU_CODELET_GET_MODE(codelet, i)
#define | STARPU_CODELET_SET_MODE(codelet, mode, i)
#define | STARPU_TASK_GET_MODE(task, i)
#define | STARPU_TASK_SET_MODE(task, mode, i)
#define | STARPU_CODELET_GET_NODE(codelet, i)
#define | STARPU_CODELET_SET_NODE(codelet, __node, i)

## Typedefs

typedef void(* | starpu_cpu_func_t) (void **, void *)
typedef void(* | starpu_cuda_func_t) (void **, void *)
typedef void(* | starpu_hip_func_t) (void **, void *)
typedef void(* | starpu_opencl_func_t) (void **, void *)
typedef void(* | starpu_max_fpga_func_t) (void **, void *)
typedef struct _starpu_trs_epoch * | starpu_trs_epoch_t

## Enumerations

enum | starpu_codelet_type { STARPU_SEQ , STARPU_SPMD , STARPU_FORKJOIN }
enum | starpu_task_status { STARPU_TASK_INIT , STARPU_TASK_INIT , STARPU_TASK_BLOCKED , STARPU_TASK_READY , STARPU_TASK_RUNNING , STARPU_TASK_FINISHED , STARPU_TASK_BLOCKED_ON_TAG , STARPU_TASK_BLOCKED_ON_TASK , STARPU_TASK_BLOCKED_ON_DATA , STARPU_TASK_STOPPED }

## Functions

void | starpu_task_init (struct starpu_task *task)
void | starpu_task_clean (struct starpu_task *task)
struct starpu_task * | starpu_task_create (void) STARPU_ATTRIBUTE_MALLOC
struct starpu_task * | starpu_task_create_sync (starpu_data_handle_t handle, enum starpu_data_access_mode mode) STARPU_ATTRIBUTE_MALLOC
void | starpu_task_destroy (struct starpu_task *task)
void | starpu_task_set_destroy (struct starpu_task *task)
int | starpu_task_submit (struct starpu_task *task)
int | starpu_task_submit_nodeps (struct starpu_task *task)
int | starpu_task_submit_to_ctx (struct starpu_task *task, unsigned sched_ctx_id)
int | starpu_task_finished (struct starpu_task *task)
int | starpu_task_wait (struct starpu_task *task)
int | starpu_task_wait_array (struct starpu_task **tasks, unsigned nb_tasks)
int | starpu_task_wait_for_all (void)
int | starpu_task_wait_for_n_submitted (unsigned n)
int | starpu_task_wait_for_all_in_ctx (unsigned sched_ctx_id)
int | starpu_task_wait_for_n_submitted_in_ctx (unsigned sched_ctx_id, unsigned n)
int | starpu_task_wait_for_no_ready (void)
int | starpu_task_nready (void)
int | starpu_task_nsubmitted (void)
void | starpu_iteration_push (unsigned long iteration)
void | starpu_iteration_pop (void)
void | starpu_do_schedule (void)
void | starpu_codelet_init (struct starpu_codelet *cl)
void | starpu_codelet_display_stats (struct starpu_codelet *cl)
struct starpu_task * | starpu_task_get_current (void)
int | starpu_task_get_current_data_node (unsigned i)
const char * | starpu_task_get_model_name (struct starpu_task *task)
const char * | starpu_task_get_name (struct starpu_task *task)
struct starpu_task * | starpu_task_dup (struct starpu_task *task)
void | starpu_task_set_implementation (struct starpu_task *task, unsigned impl)
unsigned | starpu_task_get_implementation (struct starpu_task *task)
void | starpu_create_sync_task (starpu_tag_t sync_tag, unsigned ndeps, starpu_tag_t *deps, void(*callback)(void *), void *callback_arg)
void | starpu_create_callback_task (void(*callback)(void *), void *callback_arg)
void | starpu_task_ft_prologue (void *check_ft)
struct starpu_task * | starpu_task_ft_create_retry (const struct starpu_task *meta_task, const struct starpu_task *template_task, void(*check_ft)(void *))
void | starpu_task_ft_failed (struct starpu_task *task)
void | starpu_task_ft_success (struct starpu_task *meta_task)
void | starpu_task_watchdog_set_hook (void(*hook)(void *), void *hook_arg)
char * | starpu_task_status_get_as_string (enum starpu_task_status status)
void | starpu_set_limit_min_submitted_tasks (int limit_min)
void | starpu_set_limit_max_submitted_tasks (int limit_min)

## Variables

struct starpu_codelet | starpu_codelet_nop

## Detailed Description

API to manipulate codelets and tasks.

## Data Structure Documentation

## starpu_codelet

struct starpu_codelet

The codelet structure describes a kernel that is possibly implemented on various targets. For compatibility, make sure to initialize the whole structure to zero, either by using explicit memset, or the function starpu_codelet_init(), or by letting the compiler implicitly do it in e.g. static storage case.

Note that the codelet structure needs to exist until the task is terminated. If dynamic codelet allocation is desired, release should be done no sooner than the starpu_task::callback_func callback time.

If the application wants to make the structure constant, it needs to be filled exactly as StarPU expects:

- starpu_codelet::cpu_funcs, starpu_codelet::cuda_funcs, etc. must be used instead of the deprecated starpu_codelet::cpu_func, starpu_codelet::cuda_func, etc.
- the starpu_codelet::where field must be set.

and additionally, starpu_codelet::checked must be set to 1 to tell StarPU that the conditions above are properly met. Also, the STARPU_CODELET_PROFILING environment variable must be set to 0. An example is provided in tests/main/const_codelet.c

### Data Fields

uint32_t | where
int(* | can_execute )(unsigned workerid, struct starpu_task *task, unsigned nimpl)
enum starpu_codelet_type | type
int | max_parallelism
starpu_cpu_func_t | cpu_func
starpu_cuda_func_t | cuda_func
starpu_opencl_func_t | opencl_func
starpu_cpu_func_t | cpu_funcs [STARPU_MAXIMPLEMENTATIONS]
starpu_cuda_func_t | cuda_funcs [STARPU_MAXIMPLEMENTATIONS]
char | cuda_flags [STARPU_MAXIMPLEMENTATIONS]
starpu_hip_func_t | hip_funcs [STARPU_MAXIMPLEMENTATIONS]
char | hip_flags [STARPU_MAXIMPLEMENTATIONS]
starpu_opencl_func_t | opencl_funcs [STARPU_MAXIMPLEMENTATIONS]
char | opencl_flags [STARPU_MAXIMPLEMENTATIONS]
starpu_max_fpga_func_t | max_fpga_funcs [STARPU_MAXIMPLEMENTATIONS]
const char * | cpu_funcs_name [STARPU_MAXIMPLEMENTATIONS]
starpu_bubble_func_t | bubble_func
starpu_bubble_gen_dag_func_t | bubble_gen_dag_func
int | nbuffers
enum starpu_data_access_mode | modes [STARPU_NMAXBUFS]
enum starpu_data_access_mode * | dyn_modes
unsigned | specific_nodes
int | nodes [STARPU_NMAXBUFS]
int * | dyn_nodes
struct starpu_perfmodel * | model
struct starpu_perfmodel * | energy_model
unsigned long | per_worker_stats [STARPU_NMAXWORKERS]
const char * | name
unsigned | color
void(* | callback_func )(void *)
int | flags
struct starpu_perf_counter_sample * | perf_counter_sample
struct starpu_perf_counter_sample_cl_values * | perf_counter_values
int | checked

#### Field Documentation

## where

uint32_t starpu_codelet::where

Optional field to indicate which types of processing units are able to execute the codelet. The different values STARPU_CPU, STARPU_CUDA, STARPU_HIP, STARPU_OPENCL can be combined to specify on which types of processing units the codelet can be executed. STARPU_CPU|STARPU_CUDA for instance indicates that the codelet is implemented for both CPU cores and CUDA devices while STARPU_OPENCL indicates that it is only available on OpenCL devices. If the field is unset, its value will be automatically set based on the availability of the XXX_funcs fields defined below. It can also be set to STARPU_NOWHERE to specify that no computation has to be actually done.

## can_execute

int(* starpu_codelet::can_execute) (unsigned workerid, struct starpu_task *task, unsigned nimpl)

Define a function which should return 1 if the worker designated by `workerid` can execute the `nimpl` -th implementation of `task`, 0 otherwise.

## type

enum starpu_codelet_type starpu_codelet::type

Optional field to specify the type of the codelet. The default is STARPU_SEQ, i.e. usual sequential implementation. Other values (STARPU_SPMD or STARPU_FORKJOIN) declare that a parallel implementation is also available. See ParallelTasks for details.

## max_parallelism

int starpu_codelet::max_parallelism

Optional field. If a parallel implementation is available, this denotes the maximum combined worker size that StarPU will use to execute parallel tasks for this codelet.

## cpu_func

starpu_cpu_func_t starpu_codelet::cpu_func

Deprecated:
  Optional field which has been made deprecated. One should use instead the field starpu_codelet::cpu_funcs.

## cuda_func

starpu_cuda_func_t starpu_codelet::cuda_func

Deprecated:
  Optional field which has been made deprecated. One should use instead the starpu_codelet::cuda_funcs field.

## opencl_func

starpu_opencl_func_t starpu_codelet::opencl_func

Deprecated:
  Optional field which has been made deprecated. One should use instead the starpu_codelet::opencl_funcs field.

## cpu_funcs

starpu_cpu_func_t starpu_codelet::cpu_funcs[STARPU_MAXIMPLEMENTATIONS]

Optional array of function pointers to the CPU implementations of the codelet. The functions prototype must be:

void cpu_func(void *buffers[], void *cl_arg)
starpu_codelet::cpu_func
starpu_cpu_func_t cpu_func
Definition starpu_task.h:383

The first argument being the array of data managed by the data management library, and the second argument is a pointer to the argument passed from the field starpu_task::cl_arg. If the field starpu_codelet::where is set, then the field tarpu_codelet::cpu_funcs is ignored if STARPU_CPU does not appear in the field starpu_codelet::where, it must be non-`NULL` otherwise.

## cuda_funcs

starpu_cuda_func_t starpu_codelet::cuda_funcs[STARPU_MAXIMPLEMENTATIONS]

Optional array of function pointers to the CUDA implementations of the codelet. The functions must be host-functions written in the CUDA runtime API. Their prototype must be:

void cuda_func(void *buffers[], void *cl_arg)
starpu_codelet::cuda_func
starpu_cuda_func_t cuda_func
Definition starpu_task.h:390

If the field starpu_codelet::where is set, then the field starpu_codelet::cuda_funcs is ignored if STARPU_CUDA does not appear in the field starpu_codelet::where, it must be non-`NULL` otherwise.

## cuda_flags

char starpu_codelet::cuda_flags[STARPU_MAXIMPLEMENTATIONS]

Optional array of flags for CUDA execution. They specify some semantic details about CUDA kernel execution, such as asynchronous execution.

## hip_funcs

starpu_hip_func_t starpu_codelet::hip_funcs[STARPU_MAXIMPLEMENTATIONS]

Optional array of function pointers to the HIP implementations of the codelet. The functions must be host-functions written in the HIP runtime API. Their prototype must be:

void hip_func(void *buffers[], void *cl_arg)

If the field starpu_codelet::where is set, then the field starpu_codelet::hip_funcs is ignored if STARPU_HIP does not appear in the field starpu_codelet::where, it must be non-`NULL` otherwise.

## hip_flags

char starpu_codelet::hip_flags[STARPU_MAXIMPLEMENTATIONS]

Optional array of flags for HIP execution. They specify some semantic details about HIP kernel execution, such as asynchronous execution.

## opencl_funcs

starpu_opencl_func_t starpu_codelet::opencl_funcs[STARPU_MAXIMPLEMENTATIONS]

Optional array of function pointers to the OpenCL implementations of the codelet. The functions prototype must be:

void opencl_func(void *buffers[], void *cl_arg)
starpu_codelet::opencl_func
starpu_opencl_func_t opencl_func
Definition starpu_task.h:397

If the field starpu_codelet::where field is set, then the field starpu_codelet::opencl_funcs is ignored if STARPU_OPENCL does not appear in the field starpu_codelet::where, it must be non-`NULL` otherwise.

## opencl_flags

char starpu_codelet::opencl_flags[STARPU_MAXIMPLEMENTATIONS]

Optional array of flags for OpenCL execution. They specify some semantic details about OpenCL kernel execution, such as asynchronous execution.

## max_fpga_funcs

starpu_max_fpga_func_t starpu_codelet::max_fpga_funcs[STARPU_MAXIMPLEMENTATIONS]

Optional array of function pointers to the Maxeler FPGA implementations of the codelet. The functions prototype must be:

void fpga_func(void *buffers[], void *cl_arg)

The first argument being the array of data managed by the data management library, and the second argument is a pointer to the argument passed from the field starpu_task::cl_arg. If the field starpu_codelet::where is set, then the field starpu_codelet::max_fpga_funcs is ignored if STARPU_MAX_FPGA does not appear in the field starpu_codelet::where, it must be non-`NULL` otherwise.

## cpu_funcs_name

const char* starpu_codelet::cpu_funcs_name[STARPU_MAXIMPLEMENTATIONS]

Optional array of strings which provide the name of the CPU functions referenced in the array starpu_codelet::cpu_funcs. This can be used when running on MPI MS devices for StarPU to simply look up the MPI MS function implementation through its name.

## bubble_func

starpu_bubble_func_t starpu_codelet::bubble_func

Optional function to decide if the task is to be transformed into a bubble

## bubble_gen_dag_func

starpu_bubble_gen_dag_func_t starpu_codelet::bubble_gen_dag_func

Optional function to transform the task into a new graph

## nbuffers

int starpu_codelet::nbuffers

Specify the number of arguments taken by the codelet. These arguments are managed by the DSM and are accessed from the `void *buffers[]` array. The constant argument passed with the field starpu_task::cl_arg is not counted in this number. This value should not be above STARPU_NMAXBUFS. It may be set to STARPU_VARIABLE_NBUFFERS to specify that the number of buffers and their access modes will be set in starpu_task::nbuffers and starpu_task::modes or starpu_task::dyn_modes, which thus permits to define codelets with a varying number of data.

## modes

enum starpu_data_access_mode starpu_codelet::modes[STARPU_NMAXBUFS]

Is an array of starpu_data_access_mode. It describes the required access modes to the data needed by the codelet (e.g. STARPU_RW). The number of entries in this array must be specified in the field starpu_codelet::nbuffers, and should not exceed STARPU_NMAXBUFS. If insufficient, this value can be set with the configure option --enable-maxbuffers.

## dyn_modes

enum starpu_data_access_mode* starpu_codelet::dyn_modes

Is an array of starpu_data_access_mode. It describes the required access modes to the data needed by the codelet (e.g. STARPU_RW). The number of entries in this array must be specified in the field starpu_codelet::nbuffers. This field should be used for codelets having a number of data greater than STARPU_NMAXBUFS (see SettingManyDataHandlesForATask). When defining a codelet, one should either define this field or the field starpu_codelet::modes defined above.

## specific_nodes

unsigned starpu_codelet::specific_nodes

Default value is 0. If this flag is set, StarPU will not systematically send all data to the memory node where the task will be executing, it will read the starpu_codelet::nodes or starpu_codelet::dyn_nodes array to determine, for each data, on which memory node to send it.

## nodes

int starpu_codelet::nodes[STARPU_NMAXBUFS]

Optional field. When starpu_codelet::specific_nodes is 1, this specifies the memory nodes where each data should be sent to for task execution. This can be a specific memory node (>= 0), or any of STARPU_SPECIFIC_NODE_LOCAL, STARPU_SPECIFIC_NODE_CPU, STARPU_SPECIFIC_NODE_SLOW, :STARPU_SPECIFIC_NODE_FASTSTARPU_SPECIFIC_NODE_FAST, STARPU_SPECIFIC_NODE_LOCAL_OR_CPU, STARPU_SPECIFIC_NODE_NONE.

The number of entries in this array is starpu_codelet::nbuffers, and should not exceed STARPU_NMAXBUFS.

## dyn_nodes

int* starpu_codelet::dyn_nodes

Optional field. When starpu_codelet::specific_nodes is 1, this specifies the memory nodes where each data should be sent to for task execution. The number of entries in this array is starpu_codelet::nbuffers. This field should be used for codelets having a number of data greater than STARPU_NMAXBUFS (see SettingManyDataHandlesForATask). When defining a codelet, one should either define this field or the field starpu_codelet::nodes defined above.

## model

struct starpu_perfmodel* starpu_codelet::model

Optional pointer to the task duration performance model associated to this codelet. This optional field is ignored when set to `NULL` or when its field starpu_perfmodel::symbol is not set.

## energy_model

struct starpu_perfmodel* starpu_codelet::energy_model

Optional pointer to the task energy consumption performance model associated to this codelet (in J). This optional field is ignored when set to `NULL` or when its field starpu_perfmodel::symbol is not set. In the case of parallel codelets, this has to account for all processing units involved in the parallel execution.

## per_worker_stats

unsigned long starpu_codelet::per_worker_stats[STARPU_NMAXWORKERS]

Optional array for statistics collected at runtime: this is filled by StarPU and should not be accessed directly, but for example by calling the function starpu_codelet_display_stats() (See starpu_codelet_display_stats() for details).

## name

const char* starpu_codelet::name

Optional name of the codelet. This can be useful for debugging purposes.

## color

unsigned starpu_codelet::color

Optional color of the codelet. This can be useful for debugging purposes. Value 0 acts like if this field wasn't specified. Color representation is hex triplet (for example: 0xff0000 is red, 0x0000ff is blue, 0xffa500 is orange, ...).

## callback_func

void(* starpu_codelet::callback_func) (void *)

Optional field, the default value is `NULL`. This is a function pointer of prototype `void (*f)(void *)` which specifies a possible callback. If this pointer is non-`NULL`, the callback function is executed on the host after the execution of the task. If the task defines a callback, the codelet callback is not called, unless called within the task callback function. The callback is passed the value contained in the starpu_task::callback_arg field. No callback is executed if the field is set to `NULL`.

## flags

int starpu_codelet::flags

Various flags for the codelet.

## checked

int starpu_codelet::checked

Whether _starpu_codelet_check_deprecated_fields was already done or not.

## starpu_data_descr

struct starpu_data_descr

Describe a data handle along with an access mode.

Data Fields
starpu_data_handle_t | handle | data
enum starpu_data_access_mode | mode | access mode

## starpu_task

struct starpu_task

Describe a task that can be offloaded on the various processing units managed by StarPU. It instantiates a codelet. It can either be allocated dynamically with the function starpu_task_create(), or declared statically. In the latter case, the programmer has to zero the structure starpu_task and to fill the different fields properly. The indicated default values correspond to the configuration of a task allocated with starpu_task_create().

### Data Fields

const char * | name
const char * | file
int | line
struct starpu_codelet * | cl
int32_t | where
int | nbuffers
starpu_data_handle_t * | dyn_handles
void ** | dyn_interfaces
enum starpu_data_access_mode * | dyn_modes
starpu_data_handle_t | handles [STARPU_NMAXBUFS]
void * | interfaces [STARPU_NMAXBUFS]
enum starpu_data_access_mode | modes [STARPU_NMAXBUFS]
unsigned char * | handles_sequential_consistency
void * | cl_arg
size_t | cl_arg_size
void * | cl_ret
size_t | cl_ret_size
void(* | epilogue_callback_func )(void *)
void * | epilogue_callback_arg
void(* | callback_func )(void *)
void * | callback_arg
void(* | prologue_callback_func )(void *)
void * | prologue_callback_arg
void(* | prologue_callback_pop_func )(void *)
void * | prologue_callback_pop_arg
struct starpu_transaction * | transaction
starpu_trs_epoch_t | trs_epoch
starpu_tag_t | tag_id
unsigned | cl_arg_free: 1
unsigned | cl_ret_free: 1
unsigned | callback_arg_free: 1
unsigned | epilogue_callback_arg_free: 1
unsigned | prologue_callback_arg_free: 1
unsigned | prologue_callback_pop_arg_free: 1
unsigned | use_tag: 1
unsigned | sequential_consistency: 1
unsigned | synchronous: 1
unsigned | execute_on_a_specific_worker: 1
unsigned | detach: 1
unsigned | destroy: 1
unsigned | regenerate: 1
unsigned | no_submitorder: 1
unsigned char | failed
unsigned char | scheduled
unsigned char | prefetched
unsigned | workerid
unsigned | workerorder
uint32_t * | workerids
unsigned | workerids_len
int | priority
enum starpu_task_status | status
unsigned | type
unsigned | color
unsigned | sched_ctx
int | hypervisor_tag
unsigned | possibly_parallel
starpu_task_bundle_t | bundle
struct starpu_profiling_task_info * | profiling_info
double | flops
double | predicted
double | predicted_transfer
double | predicted_start
unsigned long | bubble_parent
starpu_bubble_func_t | bubble_func
void * | bubble_func_arg
starpu_bubble_gen_dag_func_t | bubble_gen_dag_func
void * | bubble_gen_dag_func_arg
void * | sched_data

### Private Attributes

unsigned char | mf_skip
int | magic
struct starpu_task * | prev
struct starpu_task * | next
void * | starpu_private
struct starpu_omp_task * | omp_task
unsigned | nb_termination_call_required

#### Field Documentation

## name

const char* starpu_task::name

Optional name of the task. This can be useful for debugging purposes.

With starpu_task_insert() and alike this can be specified thanks to STARPU_NAME followed by the const char *.

## file

const char* starpu_task::file

Optional file name where the task was submitted. This can be useful for debugging purposes.

## line

int starpu_task::line

Optional line number where the task was submitted. This can be useful for debugging purposes.

## cl

struct starpu_codelet* starpu_task::cl

Pointer to the corresponding structure starpu_codelet. This describes where the kernel should be executed, and supplies the appropriate implementations. When set to `NULL`, no code is executed during the tasks, such empty tasks can be useful for synchronization purposes.

## where

int32_t starpu_task::where

When set, specify where the task is allowed to be executed. When unset, take the value of starpu_codelet::where.

With starpu_task_insert() and alike this can be specified thanks to STARPU_EXECUTE_WHERE followed by an unsigned long long.

## nbuffers

int starpu_task::nbuffers

Specify the number of buffers. This is only used when starpu_codelet::nbuffers is STARPU_VARIABLE_NBUFFERS.

With starpu_task_insert() and alike this is automatically computed when using STARPU_DATA_ARRAY and alike.

## dyn_handles

starpu_data_handle_t* starpu_task::dyn_handles

Keep dyn_handles, dyn_interfaces and dyn_modes before the equivalent static arrays, so we can detect dyn_handles being NULL while nbuffers being bigger that STARPU_NMAXBUFS (otherwise the overflow would put a non-NULL) Array of starpu_data_handle_t. Specify the handles to the different pieces of data accessed by the task. The number of entries in this array must be specified in the field starpu_codelet::nbuffers. This field should be used for tasks having a number of data greater than STARPU_NMAXBUFS (see SettingManyDataHandlesForATask). When defining a task, one should either define this field or the field starpu_task::handles defined below.

With starpu_task_insert() and alike this is automatically filled when using STARPU_DATA_ARRAY and alike.

## dyn_interfaces

void** starpu_task::dyn_interfaces

Array of data pointers to the memory node where execution will happen, managed by the DSM. Is used when the field starpu_task::dyn_handles is defined.

This is filled by StarPU.

## dyn_modes

enum starpu_data_access_mode* starpu_task::dyn_modes

Used only when starpu_codelet::nbuffers is STARPU_VARIABLE_NBUFFERS. Array of starpu_data_access_mode which describes the required access modes to the data needed by the codelet (e.g. STARPU_RW). The number of entries in this array must be specified in the field starpu_codelet::nbuffers. This field should be used for codelets having a number of data greater than STARPU_NMAXBUFS (see SettingManyDataHandlesForATask). When defining a codelet, one should either define this field or the field starpu_task::modes defined below.

With starpu_task_insert() and alike this is automatically filled when using STARPU_DATA_MODE_ARRAY and alike.

## handles

starpu_data_handle_t starpu_task::handles[STARPU_NMAXBUFS]

Array of starpu_data_handle_t. Specify the handles to the different pieces of data accessed by the task. The number of entries in this array must be specified in the field starpu_codelet::nbuffers, and should not exceed STARPU_NMAXBUFS. If insufficient, this value can be set with the configure option --enable-maxbuffers.

With starpu_task_insert() and alike this is automatically filled when using STARPU_R and alike.

## interfaces

void* starpu_task::interfaces[STARPU_NMAXBUFS]

Array of Data pointers to the memory node where execution will happen, managed by the DSM.

This is filled by StarPU.

## modes

enum starpu_data_access_mode starpu_task::modes[STARPU_NMAXBUFS]

Used only when starpu_codelet::nbuffers is STARPU_VARIABLE_NBUFFERS. Array of starpu_data_access_mode which describes the required access modes to the data needed by the codelet (e.g. STARPU_RW). The number of entries in this array must be specified in the field starpu_task::nbuffers, and should not exceed STARPU_NMAXBUFS. If insufficient, this value can be set with the configure option --enable-maxbuffers.

With starpu_task_insert() and alike this is automatically filled when using STARPU_DATA_MODE_ARRAY and alike.

## handles_sequential_consistency

unsigned char* starpu_task::handles_sequential_consistency

Optional pointer to an array of characters which allows to define the sequential consistency for each handle for the current task.

With starpu_task_insert() and alike this can be specified thanks to STARPU_HANDLES_SEQUENTIAL_CONSISTENCY followed by an unsigned char *

## cl_arg

void* starpu_task::cl_arg

Optional pointer which is passed to the codelet through the second argument of the codelet implementation (e.g. starpu_codelet::cpu_func or starpu_codelet::cuda_func). The default value is `NULL`.

Note that the pointer is passed unchanged to most drivers, so the application has to ensure the liveness of the pointed data, by using static memory or dynamic allocation (starpu_task::cl_arg_free can be used for convenience in that case).

For the master/slave drivers however, the content pointed by cl_arg is copied to the slave, so the size of the data must be set in starpu_task::cl_arg_size.

starpu_codelet_pack_args() and starpu_codelet_unpack_args() are helpers that can can be used to respectively pack and unpack data into and from it and update starpu_task::cl_arg_size accordingly.

With starpu_task_insert() and alike this can be specified thanks to STARPU_CL_ARGS followed by a void* and a size_t.

## cl_arg_size

size_t starpu_task::cl_arg_size

Optional field. For some specific drivers, the pointer starpu_task::cl_arg cannot not be directly given to the driver function. A buffer of size starpu_task::cl_arg_size needs to be allocated on the driver. This buffer is then filled with the starpu_task::cl_arg_size bytes starting at address starpu_task::cl_arg. In this case, the argument given to the codelet is therefore not the starpu_task::cl_arg pointer, but the address of the buffer in local store (LS) instead. This field is ignored for CPU, CUDA and OpenCL codelets, where the starpu_task::cl_arg pointer is given as such.

With starpu_task_insert() and alike this can be specified thanks to STARPU_CL_ARGS followed by a void* and a size_t.

## cl_ret

void* starpu_task::cl_ret

Optional pointer which points to the return value of submitted task. The default value is `NULL`. starpu_codelet_pack_arg() and starpu_codelet_unpack_arg() can be used to respectively pack and unpack the return value into and form it. starpu_task::cl_ret can be used for MPI support. The only requirement is that the size of the return value must be set in starpu_task::cl_ret_size .

## cl_ret_size

size_t starpu_task::cl_ret_size

Optional field. The buffer of starpu_codelet_pack_arg() and starpu_codelet_unpack_arg() can be allocated with the starpu_task::cl_ret_size bytes starting at address starpu_task::cl_ret. starpu_task::cl_ret_size can be used for MPI support.

## epilogue_callback_func

void(* starpu_task::epilogue_callback_func) (void *)

Optional field, the default value is `NULL`. This is a function pointer of prototype `void (*f)(void *)` which specifies a possible callback. If this pointer is non-`NULL`, the callback function is executed on the host after the execution of the task. Contrary to starpu_task::callback_func, it is called before releasing tasks which depend on this task, so those cannot be already executing. The callback is passed the value contained in the starpu_task::epilogue_callback_arg field. No callback is executed if the field is set to `NULL`.

With starpu_task_insert() and alike this can be specified thanks to STARPU_EPILOGUE_CALLBACK followed by the function pointer.

## epilogue_callback_arg

void* starpu_task::epilogue_callback_arg

Optional field, the default value is `NULL`. This is the pointer passed to the epilogue callback function. This field is ignored if the field starpu_task::epilogue_callback_func is set to `NULL`.

## callback_func

void(* starpu_task::callback_func) (void *)

Optional field, the default value is `NULL`. This is a function pointer of prototype `void (*f)(void *)` which specifies a possible callback. If this pointer is non-`NULL`, the callback function is executed on the host after the execution of the task. Contrary to starpu_task::epilogue_callback, it is called after releasing tasks which depend on this task, so those might already be executing. The callback is passed the value contained in the starpu_task::callback_arg field. No callback is executed if the field is set to `NULL`.

With starpu_task_insert() and alike this can be specified thanks to STARPU_CALLBACK followed by the function pointer, or thanks to STARPU_CALLBACK_WITH_ARG (or STARPU_CALLBACK_WITH_ARG_NFREE) followed by the function pointer and the argument.

## callback_arg

void* starpu_task::callback_arg

Optional field, the default value is `NULL`. This is the pointer passed to the callback function. This field is ignored if the field starpu_task::callback_func is set to `NULL`.

With starpu_task_insert() and alike this can be specified thanks to STARPU_CALLBACK_ARG followed by the argument pointer, or thanks to STARPU_CALLBACK_WITH_ARG or STARPU_CALLBACK_WITH_ARG_NFREE followed by the function pointer and the argument.

## prologue_callback_func

void(* starpu_task::prologue_callback_func) (void *)

Optional field, the default value is `NULL`. This is a function pointer of prototype `void (*f)(void *)` which specifies a possible callback. If this pointer is non-`NULL`, the callback function is executed on the host when the task becomes ready for execution, before getting scheduled. The callback is passed the value contained in the starpu_task::prologue_callback_arg field. No callback is executed if the field is set to `NULL`.

With starpu_task_insert() and alike this can be specified thanks to STARPU_PROLOGUE_CALLBACK followed by the function pointer.

## prologue_callback_arg

void* starpu_task::prologue_callback_arg

Optional field, the default value is `NULL`. This is the pointer passed to the prologue callback function. This field is ignored if the field starpu_task::prologue_callback_func is set to `NULL`.

With starpu_task_insert() and alike this can be specified thanks to STARPU_PROLOGUE_CALLBACK_ARG followed by the argument

## prologue_callback_pop_func

void(* starpu_task::prologue_callback_pop_func) (void *)

Optional field, the default value is `NULL`. This is a function pointer of prototype `void (f)(void)` which specifies a possible callback. If this pointer is non-`NULL`, the callback function is executed on the host when the task is pop-ed from the scheduler, just before getting executed. The callback is passed the value contained in the starpu_task::prologue_callback_pop_arg field. No callback is executed if the field is set to `NULL`.

With starpu_task_insert() and alike this can be specified thanks to STARPU_PROLOGUE_CALLBACK_POP followed by the function pointer.

## prologue_callback_pop_arg

void* starpu_task::prologue_callback_pop_arg

Optional field, the default value is `NULL`. This is the pointer passed to the prologue_callback_pop function. This field is ignored if the field starpu_task::prologue_callback_pop_func is set to `NULL`.

With starpu_task_insert() and alike this can be specified thanks to STARPU_PROLOGUE_CALLBACK_POP_ARG followed by the argument.

## transaction

struct starpu_transaction* starpu_task::transaction

Transaction to which the task belongs, if any

## trs_epoch

starpu_trs_epoch_t starpu_task::trs_epoch

Transaction epoch to which the task belongs, if any

## tag_id

starpu_tag_t starpu_task::tag_id

Optional field. Contain the tag associated to the task if the field starpu_task::use_tag is set, ignored otherwise.

With starpu_task_insert() and alike this can be specified thanks to STARPU_TAG followed by a starpu_tag_t.

## cl_arg_free

unsigned starpu_task::cl_arg_free

Optional field. In case starpu_task::cl_arg was allocated by the application through `malloc()`, setting starpu_task::cl_arg_free to 1 makes StarPU automatically call `free(cl_arg)` when destroying the task. This saves the user from defining a callback just for that.

With starpu_task_insert() and alike this is set to 1 when using STARPU_CL_ARGS.

## cl_ret_free

unsigned starpu_task::cl_ret_free

Optional field. In case starpu_task::cl_ret was allocated by the application through `malloc()`, setting starpu_task::cl_ret_free to 1 makes StarPU automatically call `free(cl_ret)` when destroying the task.

## callback_arg_free

unsigned starpu_task::callback_arg_free

Optional field. In case starpu_task::callback_arg was allocated by the application through `malloc()`, setting starpu_task::callback_arg_free to 1 makes StarPU automatically call `free(callback_arg)` when destroying the task.

With starpu_task_insert() and alike, this is set to 1 when using STARPU_CALLBACK_ARG or STARPU_CALLBACK_WITH_ARG, or set to 0 when using STARPU_CALLBACK_ARG_NFREE

## epilogue_callback_arg_free

unsigned starpu_task::epilogue_callback_arg_free

Optional field. In case starpu_task::epilogue_callback_arg was allocated by the application through `malloc()`, setting starpu_task::epilogue_callback_arg_free to 1 makes StarPU automatically call `free(epilogue_callback_arg)` when destroying the task.

## prologue_callback_arg_free

unsigned starpu_task::prologue_callback_arg_free

Optional field. In case starpu_task::prologue_callback_arg was allocated by the application through `malloc()`, setting starpu_task::prologue_callback_arg_free to 1 makes StarPU automatically call `free(prologue_callback_arg)` when destroying the task.

With starpu_task_insert() and alike this is set to 1 when using STARPU_PROLOGUE_CALLBACK_ARG, or set to 0 when using STARPU_PROLOGUE_CALLBACK_ARG_NFREE

## prologue_callback_pop_arg_free

unsigned starpu_task::prologue_callback_pop_arg_free

Optional field. In case starpu_task::prologue_callback_pop_arg was allocated by the application through `malloc()`, setting starpu_task::prologue_callback_pop_arg_free to 1 makes StarPU automatically call `free(prologue_callback_pop_arg)` when destroying the task.

With starpu_task_insert() and alike this is set to 1 when using STARPU_PROLOGUE_CALLBACK_POP_ARG, or set to 0 when using STARPU_PROLOGUE_CALLBACK_POP_ARG_NFREE

## use_tag

unsigned starpu_task::use_tag

Optional field, the default value is 0. If set, this flag indicates that the task should be associated with the tag contained in the starpu_task::tag_id field. Tag allow the application to synchronize with the task and to express task dependencies easily.

With starpu_task_insert() and alike this is set to 1 when using STARPU_TAG.

## sequential_consistency

unsigned starpu_task::sequential_consistency

If this flag is set (which is the default), sequential consistency is enforced for the data parameters of this task for which sequential consistency is enabled. Clearing this flag permits to disable sequential consistency for this task, even if data have it enabled.

With starpu_task_insert() and alike this can be specified thanks to STARPU_SEQUENTIAL_CONSISTENCY followed by an unsigned.

## synchronous

unsigned starpu_task::synchronous

If this flag is set, the function starpu_task_submit() is blocking and returns only when the task has been executed (or if no worker is able to process the task). Otherwise, starpu_task_submit() returns immediately.

With starpu_task_insert() and alike this can be specified thanks to STARPU_TASK_SYNCHRONOUS followed an int.

## execute_on_a_specific_worker

unsigned starpu_task::execute_on_a_specific_worker

Default value is 0. If this flag is set, StarPU will bypass the scheduler and directly affect this task to the worker specified by the field starpu_task::workerid.

With starpu_task_insert() and alike this is set to 1 when using STARPU_EXECUTE_ON_WORKER.

## detach

unsigned starpu_task::detach

Optional field, default value is 1. If this flag is set, it is not possible to synchronize with the task by the means of starpu_task_wait() later on. Internal data structures are only guaranteed to be freed once starpu_task_wait() is called if the flag is not set.

With starpu_task_insert() and alike this is set to 1.

## destroy

unsigned starpu_task::destroy

Optional value. Default value is 0 for starpu_task_init(), and 1 for starpu_task_create(). If this flag is set, the task structure will automatically be freed, either after the execution of the callback if the task is detached, or during starpu_task_wait() otherwise. If this flag is not set, dynamically allocated data structures will not be freed until starpu_task_destroy() is called explicitly. Setting this flag for a statically allocated task structure will result in undefined behaviour. The flag is set to 1 when the task is created by calling starpu_task_create(). Note that starpu_task_wait_for_all() will not free any task.

With starpu_task_insert() and alike this is set to 1.

Calling starpu_task_set_destroy() can be used to set this field to 1 after submission. Indeed this function will manage concurrency against the termination of the task.

## regenerate

unsigned starpu_task::regenerate

Optional field. If this flag is set, the task will be re-submitted to StarPU once it has been executed. This flag must not be set if the flag starpu_task::destroy is set. This flag must be set before making another task depend on this one.

With starpu_task_insert() and alike this is set to 0.

## no_submitorder

unsigned starpu_task::no_submitorder

do not allocate a submitorder id for this task

With starpu_task_insert() and alike this can be specified thanks to STARPU_TASK_NO_SUBMITORDER followed by an unsigned.

## mf_skip

unsigned char starpu_task::mf_skip

private

This is only used for tasks that use multiformat handle. This should only be used by StarPU.

## failed

unsigned char starpu_task::failed

Whether this task has failed and will thus have to be retried

Set by StarPU.

## scheduled

unsigned char starpu_task::scheduled

Whether the scheduler has pushed the task on some queue

Set by StarPU.

## prefetched

unsigned char starpu_task::prefetched

Whether the scheduler has prefetched the task's data

Set by StarPU.

## workerid

unsigned starpu_task::workerid

Optional field. If the field starpu_task::execute_on_a_specific_worker is set, this field indicates the identifier of the worker that should process this task (as returned by starpu_worker_get_id()). This field is ignored if the field starpu_task::execute_on_a_specific_worker is set to 0.

With starpu_task_insert() and alike this can be specified thanks to STARPU_EXECUTE_ON_WORKER followed by an int.

## workerorder

unsigned starpu_task::workerorder

Optional field. If the field starpu_task::execute_on_a_specific_worker is set, this field indicates the per-worker consecutive order in which tasks should be executed on the worker. Tasks will be executed in consecutive starpu_task::workerorder values, thus ignoring the availability order or task priority. See StaticScheduling for more details. This field is ignored if the field starpu_task::execute_on_a_specific_worker is set to 0.

With starpu_task_insert() and alike this can be specified thanks to STARPU_WORKER_ORDER followed by an unsigned.

## workerids

uint32_t* starpu_task::workerids

Optional field. If the field starpu_task::workerids_len is different from 0, this field indicates an array of bits (stored as uint32_t values) which indicate the set of workers which are allowed to execute the task. starpu_task::workerid takes precedence over this.

With starpu_task_insert() and alike, this can be specified along the field workerids_len thanks to STARPU_TASK_WORKERIDS followed by a number of workers and an array of bits which size is the number of workers.

## workerids_len

unsigned starpu_task::workerids_len

Optional field. This provides the number of uint32_t values in the starpu_task::workerids array.

With starpu_task_insert() and alike, this can be specified along the field workerids thanks to STARPU_TASK_WORKERIDS followed by a number of workers and an array of bits which size is the number of workers.

## priority

int starpu_task::priority

Optional field, the default value is STARPU_DEFAULT_PRIO. This field indicates a level of priority for the task. This is an integer value that must be set between the return values of the function starpu_sched_get_min_priority() for the least important tasks, and that of the function starpu_sched_get_max_priority() for the most important tasks (included). The STARPU_MIN_PRIO and STARPU_MAX_PRIO macros are provided for convenience and respectively return the value of starpu_sched_get_min_priority() and starpu_sched_get_max_priority(). Default priority is STARPU_DEFAULT_PRIO, which is always defined as 0 in order to allow static task initialization. Scheduling strategies that take priorities into account can use this parameter to take better scheduling decisions, but the scheduling policy may also ignore it.

With starpu_task_insert() and alike this can be specified thanks to STARPU_PRIORITY followed by an unsigned long long.

## status

enum starpu_task_status starpu_task::status

Current state of the task.

Call starpu_task_status_get_as_string() to get the status as a string.

Set by StarPU.

## magic

int starpu_task::magic

private

This field is set when initializing a task. The function starpu_task_submit() will fail if the field does not have the correct value. This will hence avoid submitting tasks which have not been properly initialised.

## type

unsigned starpu_task::type

Allow to get the type of task, for filtering out tasks in profiling outputs, whether it is really internal to StarPU (STARPU_TASK_TYPE_INTERNAL), a data acquisition synchronization task (STARPU_TASK_TYPE_DATA_ACQUIRE), or a normal task (STARPU_TASK_TYPE_NORMAL)

Set by StarPU.

## color

unsigned starpu_task::color

color of the task to be used in dag.dot.

With starpu_task_insert() and alike this can be specified thanks to STARPU_TASK_COLOR followed by an int.

## sched_ctx

unsigned starpu_task::sched_ctx

Scheduling context.

With starpu_task_insert() and alike this can be specified thanks to STARPU_SCHED_CTX followed by an unsigned.

## hypervisor_tag

int starpu_task::hypervisor_tag

Help the hypervisor monitor the execution of this task.

With starpu_task_insert() and alike this can be specified thanks to STARPU_HYPERVISOR_TAG followed by an int.

## possibly_parallel

unsigned starpu_task::possibly_parallel

TODO: related with sched contexts and parallel tasks

With starpu_task_insert() and alike this can be specified thanks to STARPU_POSSIBLY_PARALLEL followed by an unsigned.

## bundle

starpu_task_bundle_t starpu_task::bundle

Optional field. The bundle that includes this task. If no bundle is used, this should be `NULL`.

## profiling_info

struct starpu_profiling_task_info* starpu_task::profiling_info

Optional field. Profiling information for the task.

With starpu_task_insert() and alike this can be specified thanks to STARPU_TASK_PROFILING_INFO followed by a pointer to the appropriate struct.

## flops

double starpu_task::flops

The application can set this to the number of floating points operations that the task will have to achieve. StarPU will measure the time that the task takes, and divide the two to get the GFlop/s achieved by the task. This will allow getting GFlops/s curves from the tool `starpu_perfmodel_plot`, and is useful for the hypervisor load balancing.

With starpu_task_insert() and alike this can be specified thanks to STARPU_FLOPS followed by a double.

## predicted

double starpu_task::predicted

Output field. Predicted duration of the task in microseconds. This field is only set if the scheduling strategy uses performance models.

Set by StarPU.

## predicted_transfer

double starpu_task::predicted_transfer

Output field. Predicted data transfer duration for the task in microseconds. This field is only valid if the scheduling strategy uses performance models.

Set by StarPU.

## prev

struct starpu_task* starpu_task::prev

private

A pointer to the previous task. This should only be used by StarPU schedulers.

## next

struct starpu_task* starpu_task::next

private

A pointer to the next task. This should only be used by StarPU schedulers.

## starpu_private

void* starpu_task::starpu_private

private

This is private to StarPU, do not modify.

## omp_task

struct starpu_omp_task* starpu_task::omp_task

private

This is private to StarPU, do not modify.

## bubble_parent

unsigned long starpu_task::bubble_parent

When using hierarchical dags, the job identifier of the bubble task which created the current task

## bubble_func

starpu_bubble_func_t starpu_task::bubble_func

When using hierarchical dags, a pointer to the bubble decision function

## bubble_func_arg

void* starpu_task::bubble_func_arg

When using hierarchical dags, a pointer to an argument to be given when calling the bubble decision function

## bubble_gen_dag_func

starpu_bubble_gen_dag_func_t starpu_task::bubble_gen_dag_func

When using hierarchical dags, a pointer to the bubble DAG generation function

## bubble_gen_dag_func_arg

void* starpu_task::bubble_gen_dag_func_arg

When using hierarchical dags, a pointer to an argument to be given when calling the bubble DAG generation function

## nb_termination_call_required

unsigned starpu_task::nb_termination_call_required

private

This is private to StarPU, do not modify.

## sched_data

void* starpu_task::sched_data

This field is managed by the scheduler, is it allowed to do whatever with it. Typically, some area would be allocated on push, and released on pop.

With starpu_task_insert() and alike this is set when using STARPU_TASK_SCHED_DATA.

## Macro Definition Documentation

## STARPU_NMAXBUFS

#define STARPU_NMAXBUFS

Define the maximum number of buffers that tasks will be able to take as parameters. The default value is 8, it can be changed by using the configure option --enable-maxbuffers.

## STARPU_NOWHERE

#define STARPU_NOWHERE

To be used when setting the field starpu_codelet::where to specify that the codelet has no computation part, and thus does not need to be scheduled, and data does not need to be actually loaded. This is thus essentially used for synchronization tasks.

## STARPU_WORKER_TO_MASK

#define STARPU_WORKER_TO_MASK | ( |  | worker_archtype | ) |

Convert from enum starpu_worker_archtype to worker type mask for use in "where" fields

## STARPU_CPU

#define STARPU_CPU

To be used when setting the field starpu_codelet::where (or starpu_task::where) to specify the codelet (or the task) may be executed on a CPU processing unit.

## STARPU_CUDA

#define STARPU_CUDA

To be used when setting the field starpu_codelet::where (or starpu_task::where) to specify the codelet (or the task) may be executed on a CUDA processing unit.

## STARPU_HIP

#define STARPU_HIP

To be used when setting the field starpu_codelet::where (or starpu_task::where) to specify the codelet (or the task) may be executed on a HIP processing unit.

## STARPU_OPENCL

#define STARPU_OPENCL

To be used when setting the field starpu_codelet::where (or starpu_task::where) to specify the codelet (or the task) may be executed on a OpenCL processing unit.

## STARPU_MAX_FPGA

#define STARPU_MAX_FPGA

To be used when setting the field starpu_codelet::where (or starpu_task::where) to specify the codelet (or the task) may be executed on a MAX FPGA.

## STARPU_MPI_MS

#define STARPU_MPI_MS

To be used when setting the field starpu_codelet::where (or starpu_task::where) to specify the codelet (or the task) may be executed on a MPI Slave processing unit.

## STARPU_TCPIP_MS

#define STARPU_TCPIP_MS

To be used when setting the field starpu_codelet::where (or starpu_task::where) to specify the codelet (or the task) may be executed on a TCP/IP Slave processing unit.

## STARPU_CODELET_SIMGRID_EXECUTE

#define STARPU_CODELET_SIMGRID_EXECUTE

Value to be set in starpu_codelet::flags to execute the codelet functions even in simgrid mode.

## STARPU_CODELET_SIMGRID_EXECUTE_AND_INJECT

#define STARPU_CODELET_SIMGRID_EXECUTE_AND_INJECT

Value to be set in starpu_codelet::flags to execute the codelet functions even in simgrid mode, and later inject the measured timing inside the simulation.

## STARPU_CODELET_NOPLANS

#define STARPU_CODELET_NOPLANS

Value to be set in starpu_codelet::flags to make starpu_task_submit() not submit automatic asynchronous partitioning/unpartitioning.

## STARPU_CUDA_ASYNC

#define STARPU_CUDA_ASYNC

Value to be set in starpu_codelet::cuda_flags to allow asynchronous CUDA kernel execution. This requires to use the proper CUDA stream, see CUDA-specificOptimizations

## STARPU_HIP_ASYNC

#define STARPU_HIP_ASYNC

Value to be set in starpu_codelet::hip_flags to allow asynchronous HIP kernel execution. This requires to use the proper HIP stream

## STARPU_OPENCL_ASYNC

#define STARPU_OPENCL_ASYNC

Value to be set in starpu_codelet::opencl_flags to allow asynchronous OpenCL kernel execution. This requires to use proper queueing, see OpenCL-specificOptimizations

## STARPU_MAIN_RAM

#define STARPU_MAIN_RAM

To be used as memory node number for the main CPU memory node.

## STARPU_MULTIPLE_CPU_IMPLEMENTATIONS

#define STARPU_MULTIPLE_CPU_IMPLEMENTATIONS

Deprecated:
  Setting the field starpu_codelet::cpu_func with this macro indicates the codelet will have several implementations. The use of this macro is deprecated. One should always only define the field starpu_codelet::cpu_funcs.

## STARPU_MULTIPLE_CUDA_IMPLEMENTATIONS

#define STARPU_MULTIPLE_CUDA_IMPLEMENTATIONS

Deprecated:
  Setting the field starpu_codelet::cuda_func with this macro indicates the codelet will have several implementations. The use of this macro is deprecated. One should always only define the field starpu_codelet::cuda_funcs.

## STARPU_MULTIPLE_HIP_IMPLEMENTATIONS

#define STARPU_MULTIPLE_HIP_IMPLEMENTATIONS

Deprecated:
  Setting the field starpu_codelet::hip_func with this macro indicates the codelet will have several implementations. The use of this macro is deprecated. One should always only define the field starpu_codelet::hip_funcs.

## STARPU_MULTIPLE_OPENCL_IMPLEMENTATIONS

#define STARPU_MULTIPLE_OPENCL_IMPLEMENTATIONS

Deprecated:
  Setting the field starpu_codelet::opencl_func with this macro indicates the codelet will have several implementations. The use of this macro is deprecated. One should always only define the field starpu_codelet::opencl_funcs.

## STARPU_VARIABLE_NBUFFERS

#define STARPU_VARIABLE_NBUFFERS

Value to set in starpu_codelet::nbuffers to specify that the codelet can accept a variable number of buffers, specified in starpu_task::nbuffers.

## STARPU_SPECIFIC_NODE_LOCAL

#define STARPU_SPECIFIC_NODE_LOCAL

Value to be set in the starpu_codelet::nodes field to request StarPU to put the data in local memory of the worker running the task (this is the default behavior).

## STARPU_SPECIFIC_NODE_CPU

#define STARPU_SPECIFIC_NODE_CPU

Value to be set in the starpu_codelet::nodes field to request StarPU to put the data in CPU-accessible memory (and let StarPU choose the NUMA node).

## STARPU_SPECIFIC_NODE_SLOW

#define STARPU_SPECIFIC_NODE_SLOW

Value to be set in the starpu_codelet::nodes field to request StarPU to put the data in some slow memory.

## STARPU_SPECIFIC_NODE_FAST

#define STARPU_SPECIFIC_NODE_FAST

Value to be set in the starpu_codelet::nodes field to request StarPU to put the data in some fast memory.

## STARPU_SPECIFIC_NODE_LOCAL_OR_CPU

#define STARPU_SPECIFIC_NODE_LOCAL_OR_CPU

Value to be set in the starpu_codelet::nodes field to let StarPU decide whether to put the data in the local memory of the worker running the task, or in CPU-accessible memory (and let StarPU choose the NUMA node).

## STARPU_SPECIFIC_NODE_NONE

#define STARPU_SPECIFIC_NODE_NONE

Value to be set in the starpu_codelet::nodes field to make StarPU not actually put the data in any particular memory, i.e. the task will only get the sequential consistency dependencies, but not actually trigger any data transfer.

## STARPU_TASK_TYPE_NORMAL

#define STARPU_TASK_TYPE_NORMAL

To be used in the starpu_task::type field, for normal application tasks.

## STARPU_TASK_TYPE_INTERNAL

#define STARPU_TASK_TYPE_INTERNAL

To be used in the starpu_task::type field, for StarPU-internal tasks.

## STARPU_TASK_TYPE_DATA_ACQUIRE

#define STARPU_TASK_TYPE_DATA_ACQUIRE

To be used in the starpu_task::type field, for StarPU-internal data acquisition tasks.

## STARPU_TASK_INITIALIZER

#define STARPU_TASK_INITIALIZER

Value to be used to initialize statically allocated tasks. This is equivalent to initializing a structure starpu_task with the function starpu_task_init().

## STARPU_TASK_GET_NBUFFERS

#define STARPU_TASK_GET_NBUFFERS | ( |  | task | ) |

Return the number of buffers for `task`, i.e. starpu_codelet::nbuffers, or starpu_task::nbuffers if the former is STARPU_VARIABLE_NBUFFERS.

## STARPU_TASK_GET_HANDLE

#define STARPU_TASK_GET_HANDLE | ( |  | task,
|  |  | i
| ) |  |

Return the `i` -th data handle of `task`. If `task` is defined with a static or dynamic number of handles, will either return the `i` -th element of the field starpu_task::handles or the `i` -th element of the field starpu_task::dyn_handles (see SettingManyDataHandlesForATask)

## STARPU_TASK_GET_HANDLES

#define STARPU_TASK_GET_HANDLES | ( |  | task | ) |

Return all the data handles of `task`. If `task` is defined with a static or dynamic number of handles, will either return all the element of the field starpu_task::handles or all the elements of the field starpu_task::dyn_handles (see SettingManyDataHandlesForATask)

## STARPU_TASK_SET_HANDLE

#define STARPU_TASK_SET_HANDLE | ( |  | task,
|  |  | handle,
|  |  | i
| ) |  |

Set the `i` -th data handle of `task` with `handle`. If `task` is defined with a static or dynamic number of handles, will either set the `i` -th element of the field starpu_task::handles or the `i` -th element of the field starpu_task::dyn_handles (see SettingManyDataHandlesForATask)

## STARPU_CODELET_GET_MODE

#define STARPU_CODELET_GET_MODE | ( |  | codelet,
|  |  | i
| ) |  |

Return the access mode of the `i` -th data handle of `codelet`. If `codelet` is defined with a static or dynamic number of handles, will either return the `i` -th element of the field starpu_codelet::modes or the `i` -th element of the field starpu_codelet::dyn_modes (see SettingManyDataHandlesForATask)

## STARPU_CODELET_SET_MODE

#define STARPU_CODELET_SET_MODE | ( |  | codelet,
|  |  | mode,
|  |  | i
| ) |  |

Set the access mode of the `i` -th data handle of `codelet`. If `codelet` is defined with a static or dynamic number of handles, will either set the `i` -th element of the field starpu_codelet::modes or the `i` -th element of the field starpu_codelet::dyn_modes (see SettingManyDataHandlesForATask)

## STARPU_TASK_GET_MODE

#define STARPU_TASK_GET_MODE | ( |  | task,
|  |  | i
| ) |  |

Return the access mode of the `i` -th data handle of `task`. If `task` is defined with a static or dynamic number of handles, will either return the `i` -th element of the field starpu_task::modes or the `i` -th element of the field starpu_task::dyn_modes (see SettingManyDataHandlesForATask)

## STARPU_TASK_SET_MODE

#define STARPU_TASK_SET_MODE | ( |  | task,
|  |  | mode,
|  |  | i
| ) |  |

Set the access mode of the `i` -th data handle of `task`. If `task` is defined with a static or dynamic number of handles, will either set the `i` -th element of the field starpu_task::modes or the `i` -th element of the field starpu_task::dyn_modes (see SettingManyDataHandlesForATask)

## STARPU_CODELET_GET_NODE

#define STARPU_CODELET_GET_NODE | ( |  | codelet,
|  |  | i
| ) |  |

Return the target node of the `i` -th data handle of `codelet`. If `node` is defined with a static or dynamic number of handles, will either return the `i` -th element of the field starpu_codelet::nodes or the `i` -th element of the field starpu_codelet::dyn_nodes (see SettingManyDataHandlesForATask)

## STARPU_CODELET_SET_NODE

#define STARPU_CODELET_SET_NODE | ( |  | codelet,
|  |  | __node,
|  |  | i
| ) |  |

Set the target node of the `i` -th data handle of `codelet`. If `codelet` is defined with a static or dynamic number of handles, will either set the `i` -th element of the field starpu_codelet::nodes or the `i` -th element of the field starpu_codelet::dyn_nodes (see SettingManyDataHandlesForATask)

## Typedef Documentation

## starpu_cpu_func_t

typedef void(* starpu_cpu_func_t) (void **, void *)

CPU implementation of a codelet.

## starpu_cuda_func_t

typedef void(* starpu_cuda_func_t) (void **, void *)

CUDA implementation of a codelet.

## starpu_hip_func_t

typedef void(* starpu_hip_func_t) (void **, void *)

HIP implementation of a codelet.

## starpu_opencl_func_t

typedef void(* starpu_opencl_func_t) (void **, void *)

OpenCL implementation of a codelet.

## starpu_max_fpga_func_t

typedef void(* starpu_max_fpga_func_t) (void **, void *)

Maxeler FPGA implementation of a codelet.

## Enumeration Type Documentation

## starpu_codelet_type

enum starpu_codelet_type

Describe the type of parallel task. See ParallelTasks for details.

Enumerator
STARPU_SEQ | (default) for classical sequential tasks.
STARPU_SPMD | for a parallel task whose threads are handled by StarPU, the code has to use starpu_combined_worker_get_size() and starpu_combined_worker_get_rank() to distribute the work.
STARPU_FORKJOIN | for a parallel task whose threads are started by the codelet function, which has to use starpu_combined_worker_get_size() to determine how many threads should be started.

## starpu_task_status

enum starpu_task_status

todo

Enumerator
STARPU_TASK_INIT | The task has just been initialized.
STARPU_TASK_INIT | The task has just been initialized.
STARPU_TASK_BLOCKED | The task has just been submitted, and its dependencies has not been checked yet.
STARPU_TASK_READY | The task is ready for execution.
STARPU_TASK_RUNNING | The task is running on some worker.
STARPU_TASK_FINISHED | The task is finished executing.
STARPU_TASK_BLOCKED_ON_TAG | The task is waiting for a tag.
STARPU_TASK_BLOCKED_ON_TASK | The task is waiting for a task.
STARPU_TASK_BLOCKED_ON_DATA | The task is waiting for some data.
STARPU_TASK_STOPPED | The task is stopped.

## Function Documentation

## starpu_task_init()

void starpu_task_init | ( | struct starpu_task * | task | ) |

Initialize `task` with default values. This function is implicitly called by starpu_task_create(). By default, tasks initialized with starpu_task_init() must be deinitialized explicitly with starpu_task_clean(). Tasks can also be initialized statically, using STARPU_TASK_INITIALIZER. See PerformanceModelCalibration for more details.

## starpu_task_clean()

void starpu_task_clean | ( | struct starpu_task * | task | ) |

Release all the structures automatically allocated to execute `task`, but not the task structure itself and values set by the user remain unchanged. It is thus useful for statically allocated tasks for instance. It is also useful when users want to execute the same operation several times with as least overhead as possible. It is called automatically by starpu_task_destroy(). It has to be called only after explicitly waiting for the task or after starpu_shutdown() (waiting for the callback is not enough, since StarPU still manipulates the task after calling the callback). See PerformanceModelCalibration for more details.

## starpu_task_create()

struct starpu_task * starpu_task_create | ( | void |  | ) |

Allocate a task structure and initialize it with default values. Tasks allocated dynamically with starpu_task_create() are automatically freed when the task is terminated. This means that the task pointer can not be used any more once the task is submitted, since it can be executed at any time (unless dependencies make it wait) and thus freed at any time. If the field starpu_task::destroy is explicitly unset, the resources used by the task have to be freed by calling starpu_task_destroy(). See SubmittingATask for more details.

## starpu_task_create_sync()

struct starpu_task * starpu_task_create_sync | ( | starpu_data_handle_t | handle,
|  | enum starpu_data_access_mode | mode
| ) |  |

Allocate a task structure that does nothing but accesses data `handle` with mode `mode`. This allows to synchronize with the task graph, according to the sequential consistency, against tasks submitted before or after submitting this task. One can then use starpu_task_declare_deps_array() or starpu_task_end_dep_add() / starpu_task_end_dep_release() to add dependencies against this task before submitting it. See SynchronizationTasks for more details.

## starpu_task_destroy()

void starpu_task_destroy | ( | struct starpu_task * | task | ) |

Free the resource allocated during starpu_task_create() and associated with `task`. This function is called automatically after the execution of a task when the field starpu_task::destroy is set, which is the default for tasks created by starpu_task_create(). Calling this function on a statically allocated task results in an undefined behaviour. See Per-task Feedback and Performance Model Example for more details.

## starpu_task_set_destroy()

void starpu_task_set_destroy | ( | struct starpu_task * | task | ) |

Tell StarPU to free the resources associated with `task` when the task is over. This is equivalent to having set task->destroy = 1 before submission, the difference is that this can be called after submission and properly deals with concurrency with the task execution. See WaitingForTasks for more details.

## starpu_task_submit()

int starpu_task_submit | ( | struct starpu_task * | task | ) |

Submit `task` to StarPU. Calling this function does not mean that the task will be executed immediately as there can be data or task (tag) dependencies that are not fulfilled yet: StarPU will take care of scheduling this task with respect to such dependencies. This function returns immediately if the field starpu_task::synchronous is set to 0, and block until the termination of the task otherwise. It is also possible to synchronize the application with asynchronous tasks by the means of tags, using the function starpu_tag_wait() function for instance. In case of success, this function returns 0, a return value of `-ENODEV` means that there is no worker able to process this task (e.g. there is no GPU available and this task is only implemented for CUDA devices). starpu_task_submit() can be called from anywhere, including codelet functions and callbacks, provided that the field starpu_task::synchronous is set to 0. See SubmittingATask for more details.

## starpu_task_submit_nodeps()

int starpu_task_submit_nodeps | ( | struct starpu_task * | task | ) |

Submit `task` to StarPU with dependency bypass.

This can only be called on behalf of another task which has already taken the proper dependencies, e.g. this task is just an attempt of doing the actual computation of that task. See TaskRetry for more details.

## starpu_task_submit_to_ctx()

int starpu_task_submit_to_ctx | ( | struct starpu_task * | task,
|  | unsigned | sched_ctx_id
| ) |  |

Submit `task` to the context `sched_ctx_id`. By default, starpu_task_submit() submits the task to a global context that is created automatically by StarPU. See SubmittingTasksToAContext for more details.

## starpu_task_finished()

int starpu_task_finished | ( | struct starpu_task * | task | ) |

Return 1 if `task` is terminated. See WaitingForTasks for more details.

## starpu_task_wait()

int starpu_task_wait | ( | struct starpu_task * | task | ) |

Block until `task` has been executed. It is not possible to synchronize with a task more than once. It is not possible to wait for synchronous or detached tasks. Upon successful completion, this function returns 0. Otherwise, `-EINVAL` indicates that the specified task was either synchronous or detached. See SubmittingATask for more details.

## starpu_task_wait_array()

int starpu_task_wait_array | ( | struct starpu_task ** | tasks,
|  | unsigned | nb_tasks
| ) |  |

Allow to wait for an array of tasks. Upon successful completion, this function returns 0. Otherwise, `-EINVAL` indicates that one of the tasks was either synchronous or detached. See WaitingForTasks for more details.

## starpu_task_wait_for_all()

int starpu_task_wait_for_all | ( | void |  | ) |

Block until all the tasks that were submitted (to the current context or the global one if there is no current context) are terminated. It does not destroy these tasks. See SubmittingATask for more details.

## starpu_task_wait_for_n_submitted()

int starpu_task_wait_for_n_submitted | ( | unsigned | n | ) |

Block until there are `n` submitted tasks left (to the current context or the global one if there is no current context) to be executed. It does not destroy these tasks. See HowtoReuseMemory for more details.

## starpu_task_wait_for_all_in_ctx()

int starpu_task_wait_for_all_in_ctx | ( | unsigned | sched_ctx_id | ) |

Wait until all the tasks that were already submitted to the context `sched_ctx_id` have been terminated. See WaitingForTasks for more details.

## starpu_task_wait_for_n_submitted_in_ctx()

int starpu_task_wait_for_n_submitted_in_ctx | ( | unsigned | sched_ctx_id,
|  | unsigned | n
| ) |  |

Wait until there are `n` tasks submitted left to be executed that were already submitted to the context `sched_ctx_id`. See WaitingForTasks for more details.

## starpu_task_wait_for_no_ready()

int starpu_task_wait_for_no_ready | ( | void |  | ) |

Wait until there is no more ready task. See WaitingForTasks for more details.

## starpu_task_nready()

int starpu_task_nready | ( | void |  | ) |

Return the number of submitted tasks which are ready for execution are already executing. It thus does not include tasks waiting for dependencies. See WaitingForTasks for more details.

## starpu_task_nsubmitted()

int starpu_task_nsubmitted | ( | void |  | ) |

Return the number of submitted tasks which have not completed yet. See WaitingForTasks for more details.

## starpu_iteration_push()

void starpu_iteration_push | ( | unsigned long | iteration | ) |

Set the iteration number for all the tasks to be submitted after this call. This is typically called at the beginning of a task submission loop. This number will then show up in tracing tools. A corresponding starpu_iteration_pop() call must be made to match the call to starpu_iteration_push(), at the end of the same task submission loop, typically.

Nested calls to starpu_iteration_push() and starpu_iteration_pop() are allowed, to describe a loop nest for instance, provided that they match properly.

See Creating a Gantt Diagram for more details.

## starpu_iteration_pop()

void starpu_iteration_pop | ( | void |  | ) |

Drop the iteration number for submitted tasks. This must match a previous call to starpu_iteration_push(), and is typically called at the end of a task submission loop. See Creating a Gantt Diagram for more details.

## starpu_do_schedule()

void starpu_do_schedule | ( | void |  | ) |

See GraphScheduling for more details.

## starpu_codelet_init()

void starpu_codelet_init | ( | struct starpu_codelet * | cl | ) |

Initialize `cl` with default values. Codelets should preferably be initialized statically as shown in DefiningACodelet. However such a initialisation is not always possible, e.g. when using C++. See DefiningACodelet for more details.

## starpu_codelet_display_stats()

void starpu_codelet_display_stats | ( | struct starpu_codelet * | cl | ) |

Output on `stderr` some statistics on the codelet `cl`. See Per-codelet Feedback for more details.

## starpu_task_get_current()

struct starpu_task * starpu_task_get_current | ( | void |  | ) |

Return the task currently executed by the worker, or `NULL` if it is called either from a thread that is not a task or simply because there is no task being executed at the moment. See Per-task Feedback for more details.

## starpu_task_get_current_data_node()

int starpu_task_get_current_data_node | ( | unsigned | i | ) |

Return the memory node number of parameter `i` of the task currently executed, or -1 if it is called either from a thread that is not a task or simply because there is no task being executed at the moment.

Usually, the returned memory node number is simply the memory node for the current worker. That may however be different when using e.g. starpu_codelet::specific_nodes.

See SpecifyingATargetNode for more details.

## starpu_task_get_model_name()

const char * starpu_task_get_model_name | ( | struct starpu_task * | task | ) |

Return the name of the performance model of `task`. See Performance Model Example for more details.

## starpu_task_get_name()

const char * starpu_task_get_name | ( | struct starpu_task * | task | ) |

Return the name of `task`, i.e. either its starpu_task::name field, or the name of the corresponding performance model. See Getting Task Details for more details.

## starpu_task_dup()

struct starpu_task * starpu_task_dup | ( | struct starpu_task * | task | ) |

Allocate a task structure which is the exact duplicate of `task`. See OtherTaskUtility for more details.

## starpu_task_set_implementation()

void starpu_task_set_implementation | ( | struct starpu_task * | task,
|  | unsigned | impl
| ) |  |

This function should be called by schedulers to specify the codelet implementation to be executed when executing `task`. See SchedulingHelpers for more details.

## starpu_task_get_implementation()

unsigned starpu_task_get_implementation | ( | struct starpu_task * | task | ) |

Return the codelet implementation to be executed when executing `task`. See SchedulingHelpers for more details.

## starpu_create_sync_task()

void starpu_create_sync_task | ( | starpu_tag_t | sync_tag,
|  | unsigned | ndeps,
|  | starpu_tag_t * | deps,
|  | void(*)(void *) | callback,
|  | void * | callback_arg
| ) |  |

Create and submit an empty task that unlocks a tag once all its dependencies are fulfilled. See SynchronizationTasks for more details.

## starpu_create_callback_task()

void starpu_create_callback_task | ( | void(*)(void *) | callback,
|  | void * | callback_arg
| ) |  |

Create and submit an empty task with the given callback. See SynchronizationTasks for more details.

## starpu_task_ft_prologue()

void starpu_task_ft_prologue | ( | void * | check_ft | ) |

Function to be used as a prologue callback to enable fault tolerance for the task. This prologue will create a try-task, i.e a duplicate of the task, which will to the actual computation.

The prologue argument can be set to a check_ft function that will be called on termination of the duplicate, which can check the result of the task, and either confirm success, or resubmit another attempt. If it is not set, the default implementation is to just resubmit a new try-task.

See TaskRetry for more details.

## starpu_task_ft_create_retry()

struct starpu_task * starpu_task_ft_create_retry | ( | const struct starpu_task * | meta_task,
|  | const struct starpu_task * | template_task,
|  | void(*)(void *) | check_ft
| ) |  |

Create a try-task for a `meta_task`, given a `template_task` task template. The meta task can be passed as template on the first call, but since it is mangled by starpu_task_ft_create_retry(), further calls (typically made by the check_ft callback) need to be passed the previous try-task as template task.

`check_ft` is similar to the prologue argument of starpu_task_ft_prologue(), and is typically set to the very function calling starpu_task_ft_create_retry().

The try-task is returned, and can be modified (e.g. to change scheduling parameters) before being submitted with starpu_task_submit_nodeps().

See TaskRetry for more details.

## starpu_task_ft_failed()

void starpu_task_ft_failed | ( | struct starpu_task * | task | ) |

Record that this task failed, and should thus be retried. This is usually called from the task codelet function itself, after checking the result and noticing that the computation went wrong, and thus the task should be retried. The performance of this task execution will not be recorded for performance models.

This can only be called for a task whose data access modes are either STARPU_R and STARPU_W.

## starpu_task_ft_success()

void starpu_task_ft_success | ( | struct starpu_task * | meta_task | ) |

Notify that the try-task was successful and thus the meta-task was successful. See TaskRetry for more details.

## starpu_task_watchdog_set_hook()

void starpu_task_watchdog_set_hook | ( | void(*)(void *) | hook,
|  | void * | hook_arg
| ) |  |

Set the function to call when the watchdog detects that StarPU has not finished any task for STARPU_WATCHDOG_TIMEOUT seconds. See WatchdogSupport for more details.

## starpu_task_status_get_as_string()

char * starpu_task_status_get_as_string | ( | enum starpu_task_status | status | ) |

Return the given status as a string

## starpu_set_limit_min_submitted_tasks()

void starpu_set_limit_min_submitted_tasks | ( | int | limit_min | ) |

Specify a minimum number of submitted tasks allowed at a given time, this allows to control the task submission flow. The value can also be specified with the environment variable STARPU_LIMIT_MIN_SUBMITTED_TASKS. See HowToReduceTheMemoryFootprintOfInternalDataStructures for more details.

## starpu_set_limit_max_submitted_tasks()

void starpu_set_limit_max_submitted_tasks | ( | int | limit_min | ) |

Specify a maximum number of submitted tasks allowed at a given time, this allows to control the task submission flow. The value can also be specified with the environment variable STARPU_LIMIT_MAX_SUBMITTED_TASKS. See HowToReduceTheMemoryFootprintOfInternalDataStructures for more details.

## Variable Documentation

## starpu_codelet_nop

struct starpu_codelet starpu_codelet_nop

extern

Codelet with empty function defined for all drivers