StarPU Handbook

Data Structures | Macros | Functions
Task Insert Utility

## Data Structures
struct | starpu_codelet_pack_arg_data

## Macros
#define | STARPU_MODE_SHIFT
#define | STARPU_VALUE
#define | STARPU_CALLBACK
#define | STARPU_CALLBACK_WITH_ARG
#define | STARPU_CALLBACK_ARG
#define | STARPU_PRIORITY
#define | STARPU_DATA_ARRAY
#define | STARPU_DATA_MODE_ARRAY
#define | STARPU_TAG
#define | STARPU_HYPERVISOR_TAG
#define | STARPU_FLOPS
#define | STARPU_SCHED_CTX
#define | STARPU_PROLOGUE_CALLBACK
#define | STARPU_PROLOGUE_CALLBACK_ARG
#define | STARPU_PROLOGUE_CALLBACK_POP
#define | STARPU_PROLOGUE_CALLBACK_POP_ARG
#define | STARPU_EXECUTE_ON_WORKER
#define | STARPU_EXECUTE_WHERE
#define | STARPU_TAG_ONLY
#define | STARPU_POSSIBLY_PARALLEL
#define | STARPU_WORKER_ORDER
#define | STARPU_NAME
#define | STARPU_CL_ARGS
#define | STARPU_CL_ARGS_NFREE
#define | STARPU_TASK_DEPS_ARRAY
#define | STARPU_TASK_COLOR
#define | STARPU_HANDLES_SEQUENTIAL_CONSISTENCY
#define | STARPU_TASK_SYNCHRONOUS
#define | STARPU_TASK_END_DEPS_ARRAY
#define | STARPU_TASK_END_DEP
#define | STARPU_TASK_WORKERIDS
#define | STARPU_SEQUENTIAL_CONSISTENCY
#define | STARPU_TASK_PROFILING_INFO
#define | STARPU_TASK_NO_SUBMITORDER
#define | STARPU_CALLBACK_ARG_NFREE
#define | STARPU_CALLBACK_WITH_ARG_NFREE
#define | STARPU_PROLOGUE_CALLBACK_ARG_NFREE
#define | STARPU_PROLOGUE_CALLBACK_POP_ARG_NFREE
#define | STARPU_TASK_SCHED_DATA
#define | STARPU_SHIFTED_MODE_MAX

## Functions
int | starpu_task_set (struct starpu_task *task, struct starpu_codelet *cl,...)
struct starpu_task * | starpu_task_build (struct starpu_codelet *cl,...)
int | starpu_task_insert (struct starpu_codelet *cl,...)
int | starpu_insert_task (struct starpu_codelet *cl,...)
void | starpu_task_insert_data_make_room (struct starpu_codelet *cl, struct starpu_task *task, int *allocated_buffers, int current_buffer, int room)
void | starpu_task_insert_data_process_arg (struct starpu_codelet *cl, struct starpu_task *task, int *allocated_buffers, int *current_buffer, int arg_type, starpu_data_handle_t handle)
void | starpu_task_insert_data_process_array_arg (struct starpu_codelet *cl, struct starpu_task *task, int *allocated_buffers, int *current_buffer, int nb_handles, starpu_data_handle_t *handles)
void | starpu_task_insert_data_process_mode_array_arg (struct starpu_codelet *cl, struct starpu_task *task, int *allocated_buffers, int *current_buffer, int nb_descrs, struct starpu_data_descr *descrs)
void | starpu_codelet_pack_args (void **arg_buffer, size_t *arg_buffer_size,...)
void | starpu_codelet_pack_arg_init (struct starpu_codelet_pack_arg_data *state)
void | starpu_codelet_pack_arg (struct starpu_codelet_pack_arg_data *state, const void *ptr, size_t ptr_size)
void | starpu_codelet_pack_arg_fini (struct starpu_codelet_pack_arg_data *state, void **cl_arg, size_t *cl_arg_size)
void | starpu_codelet_unpack_args (void *cl_arg,...)
void | starpu_codelet_unpack_args_and_copyleft (void *cl_arg, void *buffer, size_t buffer_size,...)

## Detailed Description

## Data Structure Documentation

## ◆ starpu_codelet_pack_arg_data

struct starpu_codelet_pack_arg_data

Data Fields
char * | arg_buffer |
size_t | arg_buffer_size |
size_t | current_offset |
int | nargs |

## Macro Definition Documentation

## ◆ STARPU_VALUE

#define STARPU_VALUE

Used when calling starpu_task_insert(), must be followed by a pointer to a constant value and the size of the constant

## ◆ STARPU_CALLBACK

#define STARPU_CALLBACK

Used when calling starpu_task_insert(), must be followed by a pointer to a callback function

## ◆ STARPU_CALLBACK_WITH_ARG

#define STARPU_CALLBACK_WITH_ARG

Used when calling starpu_task_insert(), must be followed by two pointers: one to a callback function, and the other to be given as an argument to the callback function; this is equivalent to using both STARPU_CALLBACK and STARPU_CALLBACK_ARG.

## ◆ STARPU_CALLBACK_ARG

#define STARPU_CALLBACK_ARG

Used when calling starpu_task_insert(), must be followed by a pointer to be given as an argument to the callback function

## ◆ STARPU_PRIORITY

#define STARPU_PRIORITY

Used when calling starpu_task_insert(), must be followed by a integer defining a priority level

## ◆ STARPU_DATA_ARRAY

#define STARPU_DATA_ARRAY

Used when calling starpu_task_in_sert(), must be followed by an array of handles and the number of elements in the array (as int). This is equivalent to passing the handles as separate parameters with STARPU_R/W/RW.

## ◆ STARPU_DATA_MODE_ARRAY

#define STARPU_DATA_MODE_ARRAY

Used when calling starpu_task_in_sert(), must be followed by an array of struct starpu_data_descr and the number of elements in the array (as int). This is equivalent to passing the handles with the corresponding modes.

## ◆ STARPU_TAG

#define STARPU_TAG

Used when calling starpu_task_insert(), must be followed by a tag.

## ◆ STARPU_HYPERVISOR_TAG

#define STARPU_HYPERVISOR_TAG

Used when calling starpu_task_insert(), must be followed by a tag.

## ◆ STARPU_FLOPS

#define STARPU_FLOPS

Used when calling starpu_task_insert(), must be followed by an amount of floating point operations, as a double. Users MUST explicitly cast into double, otherwise parameter passing will not work.

## ◆ STARPU_SCHED_CTX

#define STARPU_SCHED_CTX

Used when calling starpu_task_insert(), must be followed by the id of the scheduling context to which to submit the task to.

## ◆ STARPU_PROLOGUE_CALLBACK

#define STARPU_PROLOGUE_CALLBACK

Used when calling starpu_task_insert(), must be followed by a pointer to a prologue callback function

## ◆ STARPU_PROLOGUE_CALLBACK_ARG

#define STARPU_PROLOGUE_CALLBACK_ARG

Used when calling starpu_task_insert(), must be followed by a pointer to be given as an argument to the prologue callback function

## ◆ STARPU_PROLOGUE_CALLBACK_POP

#define STARPU_PROLOGUE_CALLBACK_POP

Used when calling starpu_task_insert(), must be followed by a pointer to a prologue callback pop function

## ◆ STARPU_PROLOGUE_CALLBACK_POP_ARG

#define STARPU_PROLOGUE_CALLBACK_POP_ARG

Used when calling starpu_task_insert(), must be followed by a pointer to be given as an argument to the prologue callback pop function

## ◆ STARPU_EXECUTE_ON_WORKER

#define STARPU_EXECUTE_ON_WORKER

Used when calling starpu_task_insert(), must be followed by an integer value specifying the worker on which to execute the task (as specified by starpu_task::execute_on_a_specific_worker)

## ◆ STARPU_EXECUTE_WHERE

#define STARPU_EXECUTE_WHERE

Used when calling starpu_task_insert(), must be followed by an unsigned long long value specifying the mask of worker on which to execute the task (as specified by starpu_task::where)

## ◆ STARPU_TAG_ONLY

#define STARPU_TAG_ONLY

Used when calling starpu_task_insert(), must be followed by a tag stored in starpu_task::tag_id. Leave starpu_task::use_tag as 0.

## ◆ STARPU_POSSIBLY_PARALLEL

#define STARPU_POSSIBLY_PARALLEL

Used when calling starpu_task_insert(), must be followed by an unsigned stored in starpu_task::possibly_parallel.

## ◆ STARPU_WORKER_ORDER

#define STARPU_WORKER_ORDER

used when calling starpu_task_insert(), must be followed by an integer value specifying the worker order in which to execute the tasks (as specified by starpu_task::workerorder)

## ◆ STARPU_NAME

#define STARPU_NAME

Used when calling starpu_task_insert(), must be followed by a char * stored in starpu_task::name.

## ◆ STARPU_CL_ARGS

#define STARPU_CL_ARGS

Used when calling starpu_task_insert(), must be followed by a memory buffer containing the arguments to be given to the task, and by the size of the arguments. The memory buffer should be the result of a previous call to starpu_codelet_pack_args(), and will be freed (i.e. starpu_task::cl_arg_free will be set to 1)

## ◆ STARPU_CL_ARGS_NFREE

#define STARPU_CL_ARGS_NFREE

Used when calling starpu_task_insert(), similarly to STARPU_CL_ARGS, must be followed by a memory buffer containing the arguments to be given to the task, and by the size of the arguments. The memory buffer should be the result of a previous call to starpu_codelet_pack_args(), and will NOT be freed (i.e. starpu_task::cl_arg_free will be set to 0)

## ◆ STARPU_TASK_DEPS_ARRAY

#define STARPU_TASK_DEPS_ARRAY

Used when calling starpu_task_insert(), must be followed by a number of tasks as int, and an array containing these tasks. The function starpu_task_declare_deps_array() will be called with the given values.

## ◆ STARPU_TASK_COLOR

#define STARPU_TASK_COLOR

Used when calling starpu_task_insert(), must be followed by an integer representing a color

## ◆ STARPU_HANDLES_SEQUENTIAL_CONSISTENCY

#define STARPU_HANDLES_SEQUENTIAL_CONSISTENCY

Used when calling starpu_task_insert(), must be followed by an array of characters representing the sequential consistency for each buffer of the task.

## ◆ STARPU_TASK_SYNCHRONOUS

#define STARPU_TASK_SYNCHRONOUS

Used when calling starpu_task_insert(), must be followed by an integer stating if the task is synchronous or not

## ◆ STARPU_TASK_END_DEPS_ARRAY

#define STARPU_TASK_END_DEPS_ARRAY

Used when calling starpu_task_insert(), must be followed by a number of tasks as int, and an array containing these tasks. The function starpu_task_declare_end_deps_array() will be called with the given values.

## ◆ STARPU_TASK_END_DEP

#define STARPU_TASK_END_DEP

Used when calling starpu_task_insert(), must be followed by an integer which will be given to starpu_task_end_dep_add()

## ◆ STARPU_TASK_WORKERIDS

#define STARPU_TASK_WORKERIDS

Used when calling starpu_task_insert(), must be followed by an unsigned being a number of workers, and an array of bits which size is the number of workers, the array indicates the set of workers which are allowed to execute the task.

## ◆ STARPU_SEQUENTIAL_CONSISTENCY

#define STARPU_SEQUENTIAL_CONSISTENCY

Used when calling starpu_task_insert(), must be followed by an unsigned which sets the sequential consistency for the data parameters of the task.

## ◆ STARPU_TASK_PROFILING_INFO

#define STARPU_TASK_PROFILING_INFO

Used when calling starpu_task_insert() and alike, must be followed by a pointer to a struct starpu_profiling_task_info

## ◆ STARPU_TASK_NO_SUBMITORDER

#define STARPU_TASK_NO_SUBMITORDER

Used when calling starpu_task_insert() and alike, must be followed by an unsigned specifying not to allocate a submitorder id for the task

## ◆ STARPU_CALLBACK_ARG_NFREE

#define STARPU_CALLBACK_ARG_NFREE

Used when calling starpu_task_insert(), similarly to STARPU_CALLBACK_ARG, must be followed by a pointer to be given as an argument to the callback function, the argument will not be freed, i.e starpu_task::callback_arg_free will be set to 0

## ◆ STARPU_CALLBACK_WITH_ARG_NFREE

#define STARPU_CALLBACK_WITH_ARG_NFREE

Used when calling starpu_task_insert(), similarly to STARPU_CALLBACK_WITH_ARG, must be followed by two pointers: one to a callback function, and the other to be given as an argument to the callback function; this is equivalent to using both STARPU_CALLBACK and STARPU_CALLBACK_ARG_NFREE.

## ◆ STARPU_PROLOGUE_CALLBACK_ARG_NFREE

#define STARPU_PROLOGUE_CALLBACK_ARG_NFREE

Used when calling starpu_task_insert(), similarly to STARPU_PROLOGUE_CALLBACK_ARG, must be followed by a pointer to be given as an argument to the prologue callback function, the argument will not be freed, i.e starpu_task::prologue_callback_arg_free will be set to 0

## ◆ STARPU_PROLOGUE_CALLBACK_POP_ARG_NFREE

#define STARPU_PROLOGUE_CALLBACK_POP_ARG_NFREE

Used when calling starpu_task_insert(), similarly to STARPU_PROLOGUE_CALLBACK_POP_ARG, must be followed by a pointer to be given as an argument to the prologue callback pop function, the argument will not be freed, i.e starpu_task::prologue_callback_pop_arg_free will be set to 0

## ◆ STARPU_TASK_SCHED_DATA

#define STARPU_TASK_SCHED_DATA

Used when calling starpu_task_insert() and alike, must be followed by a void* specifying the value to be set in the sched_data field of the task.

## Function Documentation

## ◆ starpu_task_set()

int starpu_task_set | ( | struct starpu_task * | task,
|  | struct starpu_codelet * | cl,
|  |  | ...
| ) |  |

Set the given `task` corresponding to `cl` with the following arguments. The argument list must be zero-terminated. The arguments following the codelet are the same as the ones for the function starpu_task_insert(). If some arguments of type STARPU_VALUE are given, the parameter starpu_task::cl_arg_free will be set to 1.

## ◆ starpu_task_build()

struct starpu_task * starpu_task_build | ( | struct starpu_codelet * | cl,
|  |  | ...
| ) |  |

Create a task corresponding to `cl` with the following arguments. The argument list must be zero-terminated. The arguments following the codelet are the same as the ones for the function starpu_task_insert(). If some arguments of type STARPU_VALUE are given, the parameter starpu_task::cl_arg_free will be set to 1.

## ◆ starpu_task_insert()

int starpu_task_insert | ( | struct starpu_codelet * | cl,
|  |  | ...
| ) |  |

Create and submit a task corresponding to `cl` with the following given arguments. The argument list must be zero-terminated.

The arguments following the codelet can be of the following types:

- STARPU_R, STARPU_W, STARPU_RW, STARPU_SCRATCH, STARPU_REDUX an access mode followed by a data handle;
- STARPU_DATA_ARRAY followed by an array of data handles and its number of elements;
- STARPU_DATA_MODE_ARRAY followed by an array of struct starpu_data_descr, i.e data handles with their associated access modes, and its number of elements;
- STARPU_EXECUTE_ON_WORKER, STARPU_WORKER_ORDER followed by an integer value specifying the worker on which to execute the task (as specified by starpu_task::execute_on_a_specific_worker)
- the specific values STARPU_VALUE, STARPU_CALLBACK, STARPU_CALLBACK_ARG, STARPU_CALLBACK_WITH_ARG, STARPU_PRIORITY, STARPU_TAG, STARPU_TAG_ONLY, STARPU_FLOPS, STARPU_SCHED_CTX, STARPU_CL_ARGS, STARPU_CL_ARGS_NFREE, STARPU_TASK_DEPS_ARRAY, STARPU_TASK_COLOR, STARPU_HANDLES_SEQUENTIAL_CONSISTENCY, STARPU_TASK_SYNCHRONOUS, STARPU_TASK_END_DEP followed by the appropriated objects as defined elsewhere.

When using STARPU_DATA_ARRAY, the access mode of the data handles is not defined, it will be taken from the codelet starpu_codelet::modes or starpu_codelet::dyn_modes field. One should use STARPU_DATA_MODE_ARRAY to define the data handles along with the access modes.

Parameters to be passed to the codelet implementation are defined through the type STARPU_VALUE. The function starpu_codelet_unpack_args() must be called within the codelet implementation to retrieve them.

## ◆ starpu_insert_task()

int starpu_insert_task | ( | struct starpu_codelet * | cl,
|  |  | ...
| ) |  |

Similar to starpu_task_insert(). Kept to avoid breaking old codes.

## ◆ starpu_task_insert_data_make_room()

void starpu_task_insert_data_make_room | ( | struct starpu_codelet * | cl,
|  | struct starpu_task * | task,
|  | int * | allocated_buffers,
|  | int | current_buffer,
|  | int | room
| ) |  |

Assuming that there are already `current_buffer` data handles passed to the task, and if *allocated_buffers is not 0, the `task->dyn_handles` array has size `*allocated_buffers`, this function makes room for `room` other data handles, allocating or reallocating `task->dyn_handles` as necessary and updating `allocated_buffers` accordingly. One can thus start with allocated_buffers equal to 0 and current_buffer equal to 0, then make room by calling this function, then store handles with STARPU_TASK_SET_HANDLE(), make room again with this function, store yet more handles, etc.

## ◆ starpu_task_insert_data_process_arg()

void starpu_task_insert_data_process_arg | ( | struct starpu_codelet * | cl,
|  | struct starpu_task * | task,
|  | int * | allocated_buffers,
|  | int * | current_buffer,
|  | int | arg_type,
|  | starpu_data_handle_t | handle
| ) |  |

Store data handle `handle` into task `task` with mode `arg_type`, updating `*allocated_buffers` and `*current_buffer` accordingly.

## ◆ starpu_task_insert_data_process_array_arg()

void starpu_task_insert_data_process_array_arg | ( | struct starpu_codelet * | cl,
|  | struct starpu_task * | task,
|  | int * | allocated_buffers,
|  | int * | current_buffer,
|  | int | nb_handles,
|  | starpu_data_handle_t * | handles
| ) |  |

Store `nb_handles` data handles `handles` into task `task`, updating `*allocated_buffers` and `*current_buffer` accordingly.

## ◆ starpu_task_insert_data_process_mode_array_arg()

void starpu_task_insert_data_process_mode_array_arg | ( | struct starpu_codelet * | cl,
|  | struct starpu_task * | task,
|  | int * | allocated_buffers,
|  | int * | current_buffer,
|  | int | nb_descrs,
|  | struct starpu_data_descr * | descrs
| ) |  |

Store `nb_descrs` data handles described by `descrs` into task `task`, updating `*allocated_buffers` and `*current_buffer` accordingly.

## ◆ starpu_codelet_pack_args()

void starpu_codelet_pack_args | ( | void ** | arg_buffer,
|  | size_t * | arg_buffer_size,
|  |  | ...
| ) |  |

Pack arguments of type STARPU_VALUE into a buffer which can be given to a codelet and later unpacked with the function starpu_codelet_unpack_args().

Instead of calling starpu_codelet_pack_args(), one can also call starpu_codelet_pack_arg_init(), then starpu_codelet_pack_arg() for each data, then starpu_codelet_pack_arg_fini().

## ◆ starpu_codelet_pack_arg_init()

void starpu_codelet_pack_arg_init | ( | struct starpu_codelet_pack_arg_data * | state | ) |

Initialize struct starpu_codelet_pack_arg before calling starpu_codelet_pack_arg() and starpu_codelet_pack_arg_fini(). This will simply initialize the content of the structure.

## ◆ starpu_codelet_pack_arg()

void starpu_codelet_pack_arg | ( | struct starpu_codelet_pack_arg_data * | state,
|  | const void * | ptr,
|  | size_t | ptr_size
| ) |  |

Pack one argument into struct starpu_codelet_pack_arg `state`. That structure has to be initialized before with starpu_codelet_pack_arg_init(), and after all starpu_codelet_pack_arg() calls performed, starpu_codelet_pack_arg_fini() has to be used to get the `cl_arg` and `cl_arg_size` to be put in the task.

## ◆ starpu_codelet_pack_arg_fini()

void starpu_codelet_pack_arg_fini | ( | struct starpu_codelet_pack_arg_data * | state,
|  | void ** | cl_arg,
|  | size_t * | cl_arg_size
| ) |  |

Finish packing data, after calling starpu_codelet_pack_arg_init() once and starpu_codelet_pack_arg() several times.

## ◆ starpu_codelet_unpack_args()

void starpu_codelet_unpack_args | ( | void * | cl_arg,
|  |  | ...
| ) |  |

Retrieve the arguments of type STARPU_VALUE associated to a task automatically created using the function starpu_task_insert(). If any parameter's value is 0, unpacking will stop there and ignore the remaining parameters.

## ◆ starpu_codelet_unpack_args_and_copyleft()

void starpu_codelet_unpack_args_and_copyleft | ( | void * | cl_arg,
|  | void * | buffer,
|  | size_t | buffer_size,
|  |  | ...
| ) |  |

Similar to starpu_codelet_unpack_args(), but if any parameter is 0, copy the part of `cl_arg` that has not been read in `buffer` which can then be used in a later call to one of the unpack functions.