/* 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: 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 MUST 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 task->dyn_handles array has size \p *allocated_buffers, this function makes room for \p room other data handles, allocating or reallocating task->dyn_handles 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. */