starpu-max/doc/doxygen/chapters/api/insert_task.doxy

/* StarPU --- Runtime system for heterogeneous multicore architectures.
 *
 * Copyright (C) 2010-2019                                CNRS
 * Copyright (C) 2009-2011,2014-2016,2018                 Université de Bordeaux
 * Copyright (C) 2011,2012                                Inria
 *
 * StarPU is free software; you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation; either version 2.1 of the License, or (at
 * your option) any later version.
 *
 * StarPU is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 *
 * See the GNU Lesser General Public License in COPYING.LGPL for more details.
 */

/*! \defgroup API_Insert_Task Task Insert Utility

\fn int starpu_insert_task(struct starpu_codelet *cl, ...)
\ingroup API_Insert_Task
Similar to starpu_task_insert(). Kept to avoid breaking old codes.

\fn int starpu_task_insert(struct starpu_codelet *cl, ...)
\ingroup API_Insert_Task
Create and submit a task corresponding to \p cl with the
following given arguments. The argument list must be zero-terminated.

The arguments following the codelet can be of the following types:
<ul>
<li> ::STARPU_R, ::STARPU_W, ::STARPU_RW, ::STARPU_SCRATCH,
::STARPU_REDUX an access mode followed by a data handle;
<li> ::STARPU_DATA_ARRAY followed by an array of data handles and its
number of elements;
<li> ::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;
<li> ::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)
<li> 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.
</ul>

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.

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

\def STARPU_CL_ARGS
\ingroup API_Insert_Task
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)

\def STARPU_CL_ARGS_NFREE
\ingroup API_Insert_Task
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)

\def STARPU_CALLBACK
\ingroup API_Insert_Task
Used when calling starpu_task_insert(), must
be followed by a pointer to a callback function

\def STARPU_CALLBACK_WITH_ARG
\ingroup API_Insert_Task
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_WITH_ARG.

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

\def STARPU_PRIORITY
\ingroup API_Insert_Task
Used when calling starpu_task_insert(), must
be followed by a integer defining a priority level

\def STARPU_DATA_ARRAY
\ingroup API_Insert_Task
TODO

\def STARPU_DATA_MODE_ARRAY
\ingroup API_Insert_Task
TODO

\def STARPU_EXECUTE_ON_WORKER
\ingroup API_Insert_Task
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)

\def STARPU_WORKER_ORDER
\ingroup API_Insert_Task
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)

\def STARPU_TAG
\ingroup API_Insert_Task
Used when calling starpu_task_insert(), must be followed by a tag.

\def STARPU_TAG_ONLY
\ingroup API_Insert_Task
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.

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

\def STARPU_FLOPS
\ingroup API_Insert_Task
Used when calling starpu_task_insert(), must
be followed by an amount of floating point operations, as a double.
Users <b>MUST</b> explicitly cast into double, otherwise parameter
passing will not work.

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

\def STARPU_TASK_DEPS_ARRAY
\ingroup API_Insert_Task
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.

\def STARPU_TASK_END_DEPS_ARRAY
\ingroup API_Insert_Task
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.

\def STARPU_TASK_COLOR
\ingroup API_Insert_Task
Used when calling starpu_task_insert(), must be followed by an integer
representing a color

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

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

\def STARPU_TASK_END_DEP
\ingroup API_Insert_Task
Used when calling starpu_task_insert(), must be followed by an integer
which will be given to starpu_task_end_dep_add()

\fn void starpu_task_insert_data_make_room(struct starpu_codelet *cl, struct starpu_task *task, int *allocated_buffers, int current_buffer, int room)
\ingroup API_Insert_Task
Assuming that there are already \p current_buffer data handles passed to
the task, and if *allocated_buffers is not 0, the <c>task->dyn_handles</c>
array has size \p *allocated_buffers, this function makes room for \p room
other data handles, allocating or reallocating <c>task->dyn_handles</c> as
necessary and updating \p *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.

\fn 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)
\ingroup API_Insert_Task
Store data handle \p handle into task \p task with mode \p arg_type,
updating \p *allocated_buffers and \p *current_buffer accordingly.

\fn 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)
\ingroup API_Insert_Task
Store \p nb_handles data handles \p handles into task \p task, updating \p
*allocated_buffers and \p *current_buffer accordingly.

\fn 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);
\ingroup API_Insert_Task
Store \p nb_descrs data handles described by \p descrs into task \p task,
updating \p *allocated_buffers and \p *current_buffer accordingly.

\fn void starpu_codelet_pack_args(void **arg_buffer, size_t *arg_buffer_size, ...)
\ingroup API_Insert_Task
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().

\fn void starpu_codelet_pack_arg_init(struct starpu_codelet_pack_arg_data *state)
\ingroup API_Insert_Task
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.

\fn void starpu_codelet_pack_arg(struct starpu_codelet_pack_arg_data *state, const void *ptr, size_t ptr_size)
\ingroup API_Insert_Task
Pack one argument into struct starpu_codelet_pack_arg \p 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 \p cl_arg and \p cl_arg_size to be put in the task.

\fn void starpu_codelet_pack_arg_fini(struct starpu_codelet_pack_arg_data *state, void **cl_arg, size_t *cl_arg_size)
\ingroup API_Insert_Task
Finish packing data, after calling starpu_codelet_pack_arg_init() once and starpu_codelet_pack_arg() several times.

\fn void starpu_codelet_unpack_args(void *cl_arg, ...)
\ingroup API_Insert_Task
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.

\fn void starpu_codelet_unpack_args_and_copyleft(void *cl_arg, void *buffer, size_t buffer_size, ...)
\ingroup API_Insert_Task
Similar to starpu_codelet_unpack_args(), but if any parameter is
0, copy the part of \p cl_arg that has not been read in \p buffer which
can then be used in a later call to one of the unpack functions.

\fn struct starpu_task *starpu_task_build(struct starpu_codelet *cl, ...)
\ingroup API_Insert_Task
Create a task corresponding to \p 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.

\fn int starpu_task_set(struct starpu_task *task, struct starpu_codelet *cl, ...)
\ingroup API_Insert_Task
Set the given \p task corresponding to \p 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.

*/