moving public api documentation from doxygen files to .h files

Makefile.am

@@ -74,6 +74,7 @@ versinclude_HEADERS = 				\
 	include/starpu_data_interfaces.h	\
 	include/starpu_worker.h			\
 	include/starpu_task.h			\
+	include/starpu_task_dep.h		\
 	include/starpu_task_bundle.h		\
 	include/starpu_task_list.h		\
 	include/starpu_task_util.h		\

doc/doxygen/Makefile.am

@@ -105,10 +105,8 @@ chapters =	\
 	chapters/code/disk_compute.c \
 	chapters/code/nf_initexit.f90 \
 	chapters/api/codelet_and_tasks.doxy \
-	chapters/api/explicit_dependencies.doxy \
 	chapters/api/fft_support.doxy \
 	chapters/api/initialization.doxy \
-	chapters/api/insert_task.doxy \
 	chapters/api/misc_helpers.doxy \
 	chapters/api/mpi.doxy \
 	chapters/api/opencl_extensions.doxy \
@@ -118,14 +116,9 @@ chapters =	\
 	chapters/api/parallel_tasks.doxy \
 	chapters/api/scheduling_contexts.doxy \
 	chapters/api/scheduling_policy.doxy \
-	chapters/api/standard_memory_library.doxy \
-	chapters/api/task_bundles.doxy \
-	chapters/api/task_lists.doxy \
-	chapters/api/top.doxy \
 	chapters/api/versioning.doxy \
 	chapters/api/workers.doxy \
 	chapters/api/threads.doxy \
-	chapters/api/tree.doxy \
 	chapters/api/toolbox.doxy \
 	chapters/api/sc_hypervisor/sc_hypervisor.doxy \
 	chapters/api/sc_hypervisor/sc_hypervisor_usage.doxy \
@@ -246,6 +239,7 @@ dox_inputs = $(DOX_CONFIG) 				\
 	$(top_srcdir)/include/starpu_sink.h		\
 	$(top_srcdir)/include/starpu_stdlib.h		\
 	$(top_srcdir)/include/starpu_task_bundle.h	\
+	$(top_srcdir)/include/starpu_task_dep.h		\
 	$(top_srcdir)/include/starpu_task.h		\
 	$(top_srcdir)/include/starpu_task_list.h	\
 	$(top_srcdir)/include/starpu_task_util.h	\

doc/doxygen/chapters/api/explicit_dependencies.doxy

@@ -1,179 +0,0 @@
-/* StarPU --- Runtime system for heterogeneous multicore architectures.
- *
- * Copyright (C) 2010-2013,2015,2017,2018                 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_Explicit_Dependencies Explicit Dependencies
-
-\fn void starpu_task_declare_deps_array(struct starpu_task *task, unsigned ndeps, struct starpu_task *task_array[])
-\ingroup API_Explicit_Dependencies
-Declare task dependencies between a \p task and an array of
-tasks of length \p ndeps. This function must be called prior to the
-submission of the task, but it may called after the submission or the
-execution of the tasks in the array, provided the tasks are still
-valid (i.e. they were not automatically destroyed). Calling this
-function on a task that was already submitted or with an entry of
-\p task_array that is no longer a valid task results in an undefined
-behaviour. If \p ndeps is 0, no dependency is added. It is possible to
-call starpu_task_declare_deps_array() several times on the same task,
-in this case, the dependencies are added. It is possible to have
-redundancy in the task dependencies.
-
-\fn void starpu_task_declare_deps(starpu_task *task, unsigned ndeps, ...)
-\ingroup API_Explicit_Dependencies
-Declare task dependencies between a \p task and an series of \p ndeps tasks,
-similarly to starpu_task_declare_deps_array(), but the tasks are passed after \p
-ndeps, which indicates how many tasks \p task shall be made to depend on.
-If \p ndeps is 0, no dependency is added.
-
-\fn void starpu_task_declare_end_deps_array(struct starpu_task *task, unsigned ndeps, struct starpu_task *task_array[])
-\ingroup API_Explicit_Dependencies
-Declare task end dependencies between a \p task and an array of
-tasks of length \p ndeps. \p task will appear as terminated not only when \p
-task is termination, but also when the tasks of \p task_array have terminated.
-This function must be called prior to the
-termination of the task, but it may called after the submission or the
-execution of the tasks in the array, provided the tasks are still
-valid (i.e. they were not automatically destroyed). Calling this
-function on a task that was already terminated or with an entry of
-\p task_array that is no longer a valid task results in an undefined
-behaviour. If \p ndeps is 0, no dependency is added. It is possible to
-call starpu_task_declare_end_deps_array() several times on the same task,
-in this case, the dependencies are added. It is currently not implemented to have
-redundancy in the task dependencies.
-
-\fn void starpu_task_declare_end_deps(starpu_task *task, unsigned ndeps, ...)
-\ingroup API_Explicit_Dependencies
-Declare task end dependencies between a \p task and an series of \p ndeps tasks,
-similarly to starpu_task_declare_end_deps_array(), but the tasks are passed after \p
-ndeps, which indicates how many tasks \p task 's termination shall be made to depend on.
-If \p ndeps is 0, no dependency is added.
-
-\fn int starpu_task_get_task_succs(struct starpu_task *task, unsigned ndeps, struct starpu_task *task_array[])
-\ingroup API_Explicit_Dependencies
-Fill \p task_array with the list of tasks which are direct children of \p task.
-\p ndeps is the size of \p task_array.  This function returns the number of
-direct children. \p task_array can be set to <c>NULL</c> if \p ndeps is 0, which allows
-to compute the number of children before allocating an array to store them.
-This function can only be called if \p task has not completed yet, otherwise
-the results are undefined. The result may also be outdated if some additional
-dependency has been added in the meanwhile.
-
-\fn int starpu_task_get_task_scheduled_succs(struct starpu_task *task, unsigned ndeps, struct starpu_task *task_array[])
-\ingroup API_Explicit_Dependencies
-Behave like starpu_task_get_task_succs(), except that it only reports
-tasks which will go through the scheduler, thus avoiding tasks with not codelet,
-or with explicit placement.
-
-\typedef starpu_tag_t
-\ingroup API_Explicit_Dependencies
-Define a task logical identifer. It is possible to
-associate a task with a unique <em>tag</em> chosen by the application,
-and to express dependencies between tasks by the means of those tags.
-To do so, fill the field starpu_task::tag_id with a tag number (can be
-arbitrary) and set the field starpu_task::use_tag to 1. If
-starpu_tag_declare_deps() is called with this tag number, the task
-will not be started until the tasks which holds the declared
-dependency tags are completed.
-
-\fn void starpu_tag_declare_deps(starpu_tag_t id, unsigned ndeps, ...)
-\ingroup API_Explicit_Dependencies
-Specify the dependencies of the task identified by tag \p id.
-The first argument specifies the tag which is configured, the second
-argument gives the number of tag(s) on which \p id depends. The
-following arguments are the tags which have to be terminated to unlock
-the task. This function must be called before the associated task is
-submitted to StarPU with starpu_task_submit().
-
-<b>WARNING! Use with caution</b>. Because of the variable arity of
-starpu_tag_declare_deps(), note that the last arguments must be of
-type ::starpu_tag_t : constant values typically need to be explicitly
-casted. Otherwise, due to integer sizes and argument passing on the
-stack, the C compiler might consider the tag <c>0x200000003</c>
-instead of <c>0x2</c> and <c>0x3</c> when calling
-<c>starpu_tag_declare_deps(0x1, 2, 0x2, 0x3)</c>. Using the
-starpu_tag_declare_deps_array() function avoids this hazard.
-
-\code{.c}
-/*  Tag 0x1 depends on tags 0x32 and 0x52 */
-starpu_tag_declare_deps((starpu_tag_t)0x1, 2, (starpu_tag_t)0x32, (starpu_tag_t)0x52);
-\endcode
-
-\fn void starpu_tag_declare_deps_array(starpu_tag_t id, unsigned ndeps, starpu_tag_t *array)
-\ingroup API_Explicit_Dependencies
-Similar to starpu_tag_declare_deps(), except
-that its does not take a variable number of arguments but an \p array of
-tags of size \p ndeps.
-
-\code{.c}
-/*  Tag 0x1 depends on tags 0x32 and 0x52 */
-starpu_tag_t tag_array[2] = {0x32, 0x52};
-starpu_tag_declare_deps_array((starpu_tag_t)0x1, 2, tag_array);
-\endcode
-
-\fn int starpu_tag_wait(starpu_tag_t id)
-\ingroup API_Explicit_Dependencies
-Block until the task associated to tag \p id has
-been executed. This is a blocking call which must therefore not be
-called within tasks or callbacks, but only from the application
-directly. It is possible to synchronize with the same tag multiple
-times, as long as the starpu_tag_remove() function is not called. Note
-that it is still possible to synchronize with a tag associated to a
-task for which the strucuture starpu_task was freed (e.g. if the field
-starpu_task::destroy was enabled).
-
-\fn int starpu_tag_wait_array(unsigned ntags, starpu_tag_t *id)
-\ingroup API_Explicit_Dependencies
-Similar to starpu_tag_wait() except that it
-blocks until all the \p ntags tags contained in the array \p id are
-terminated.
-
-\fn void starpu_tag_restart(starpu_tag_t id)
-\ingroup API_Explicit_Dependencies
-Clear the <em>already notified</em> status of a tag which is not associated with a task.
-Before that, calling starpu_tag_notify_from_apps() again will not
-notify the successors. After that, the next call to
-starpu_tag_notify_from_apps() will notify the successors.
-
-\fn void starpu_tag_remove(starpu_tag_t id)
-\ingroup API_Explicit_Dependencies
-Release the resources associated to tag \p id.
-It can be called once the corresponding task has been executed and
-when there is no other tag that depend on this tag anymore.
-
-\fn void starpu_tag_notify_from_apps(starpu_tag_t id)
-\ingroup API_Explicit_Dependencies
-Explicitly unlock tag \p id. It may be useful in
-the case of applications which execute part of their computation
-outside StarPU tasks (e.g. third-party libraries). It is also provided
-as a convenient tool for the programmer, for instance to entirely
-construct the task DAG before actually giving StarPU the opportunity
-to execute the tasks. When called several times on the same tag,
-notification will be done only on first call, thus implementing "OR"
-dependencies, until the tag is restarted using starpu_tag_restart().
-
-\fn void starpu_task_end_dep_add(struct starpu_task *t, int nb_deps)
-\ingroup API_Explicit_Dependencies
-Add \p nb_deps end dependencies to the task \p t. This means the task
-will not terminate until the required number of calls to the function
-starpu_task_end_dep_release() has been made.
-
-\fn void starpu_task_end_dep_release(struct starpu_task *t)
-\ingroup API_Explicit_Dependencies
-Unlock 1 end dependency to the task \p t. This function must be called
-after starpu_task_end_dep_add().
-
-*/

doc/doxygen/chapters/api/insert_task.doxy

@@ -1,271 +0,0 @@
-/* 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.
-
-*/

doc/doxygen/chapters/api/scheduling_contexts.doxy

@@ -17,327 +17,11 @@
  * See the GNU Lesser General Public License in COPYING.LGPL for more details.
  */
 
-/*! \defgroup API_Scheduling_Contexts Scheduling Contexts
-
-\brief StarPU permits on one hand grouping workers in combined workers
-in order to execute a parallel task and on the other hand grouping
-tasks in bundles that will be executed by a single specified worker.
-In contrast when we group workers in scheduling contexts we submit
-starpu tasks to them and we schedule them with the policy assigned to
-the context. Scheduling contexts can be created, deleted and modified
-dynamically.
-
-\struct starpu_sched_ctx_performance_counters
-Performance counters used by the starpu to indicate the
-hypervisor how the application and the resources are executing.
-\ingroup API_Scheduling_Contexts
-\var void (*starpu_sched_ctx_performance_counters::notify_idle_cycle)(unsigned sched_ctx_id, int worker, double idle_time)
-        Inform the hypervisor for how long a worker has been idle in the specified context
-\var void (*starpu_sched_ctx_performance_counters::notify_pushed_task)(unsigned sched_ctx_id, int worker)
-        Notify the hypervisor that a task has been scheduled on the queue of the worker corresponding to the specified context
-\var void (*starpu_sched_ctx_performance_counters::notify_poped_task)(unsigned sched_ctx_id, int worker)
-        Inform the hypervisor that a task executing a specified number of instructions has been poped from the worker
-\var void (*starpu_sched_ctx_performance_counters::notify_post_exec_task)(struct starpu_task *task, size_t data_size, uint32_t footprint, int hypervisor_tag, double flops)
-        Notify the hypervisor that a task has just been executed
-\var void (*starpu_sched_ctx_performance_counters::notify_submitted_job)(struct starpu_task *task, uint32_t footprint, size_t data_size)
-        Notify the hypervisor that a task has just been submitted
-\var void (*starpu_sched_ctx_performance_counters::notify_delete_context)(unsigned sched_ctx)
-        Notify the hypervisor that the context was deleted
-
-
-@name Scheduling Contexts Basic API
-\ingroup API_Scheduling_Contexts
+/*! \ingroup API_Scheduling_Contexts
 
 \def STARPU_NMAX_SCHED_CTXS
 \ingroup API_Scheduling_Policy
 Define the maximum number of scheduling contexts managed by StarPU. The default value can be
 modified at configure by using the option \ref enable-max-sched-ctxs "--enable-max-sched-ctxs".
 
-\fn unsigned starpu_sched_ctx_create(int *workerids_ctx, int nworkers_ctx, const char *sched_ctx_name, ...)
-\ingroup API_Scheduling_Contexts
-Create a scheduling context with the given parameters
-(see below) and assigns the workers in \p workerids_ctx to execute the
-tasks submitted to it. The return value represents the identifier of
-the context that has just been created. It will be further used to
-indicate the context the tasks will be submitted to. The return value
-should be at most ::STARPU_NMAX_SCHED_CTXS.
-
-The arguments following the name of the scheduling context can be of
-the following types:
-<ul>
-<li> ::STARPU_SCHED_CTX_POLICY_NAME, followed by the name of a
-predefined scheduling policy. Use an empty string to create the
-context with the default scheduling policy.
-</li>
-<li> ::STARPU_SCHED_CTX_POLICY_STRUCT, followed by a pointer to a
-custom scheduling policy (struct starpu_sched_policy *)
-</li>
-<li> ::STARPU_SCHED_CTX_POLICY_MIN_PRIO, followed by a integer
-representing the minimum priority value to be defined for the
-scheduling policy.
-</li>
-<li> ::STARPU_SCHED_CTX_POLICY_MAX_PRIO, followed by a integer
-representing the maximum priority value to be defined for the
-scheduling policy.
-</li>
-<li> ::STARPU_SCHED_CTX_POLICY_INIT, followed by a function pointer
-(ie. void init_sched(void)) allowing to initialize the scheduling policy.
-</li>
-<li> ::STARPU_SCHED_CTX_USER_DATA, followed by a pointer
-to a custom user data structure, to be retrieved by \ref starpu_sched_ctx_get_user_data().
-</li>
-</ul>
-
-\def STARPU_SCHED_CTX_POLICY_NAME
-\ingroup API_Scheduling_Contexts
-Used when calling starpu_sched_ctx_create() to specify a
-name for a scheduling policy
-
-\def STARPU_SCHED_CTX_POLICY_STRUCT
-\ingroup API_Scheduling_Contexts
-Used when calling starpu_sched_ctx_create() to specify a
-pointer to a scheduling policy
-
-\def STARPU_SCHED_CTX_POLICY_MIN_PRIO
-\ingroup API_Scheduling_Contexts
-Used when calling starpu_sched_ctx_create() to specify a
-minimum scheduler priority value.
-
-\def STARPU_SCHED_CTX_POLICY_MAX_PRIO
-\ingroup API_Scheduling_Contexts
-Used when calling starpu_sched_ctx_create() to specify a
-maximum scheduler priority value.
-
-\def STARPU_SCHED_CTX_AWAKE_WORKERS
-\ingroup API_Scheduling_Contexts
-Used when calling starpu_sched_ctx_create() to specify ???
-
-\def STARPU_SCHED_CTX_POLICY_INIT
-\ingroup API_Scheduling_Contexts
-Used when calling starpu_sched_ctx_create() to specify a
-function pointer allowing to initialize the scheduling policy.
-
-\def STARPU_SCHED_CTX_USER_DATA
-\ingroup API_Scheduling_Contexts
-Used when calling starpu_sched_ctx_create() to specify a
-pointer to some user data related to the context being created.
-
-\def STARPU_SCHED_CTX_SUB_CTXS
-\ingroup API_Scheduling_Contexts
-Used when calling starpu_sched_ctx_create() to specify
-a list of sub contextes of the current context.
-
-\def STARPU_SCHED_CTX_CUDA_NSMS
-\ingroup API_Scheduling_Contexts
-Used when calling starpu_sched_ctx_create() in order
-to create a context on the NVIDIA GPU to specify the number of SMs
-the context should have
-
-\fn unsigned starpu_sched_ctx_create_inside_interval(const char *policy_name, const char *sched_ctx_name, int min_ncpus, int max_ncpus, int min_ngpus, int max_ngpus, unsigned allow_overlap)
-\ingroup API_Scheduling_Contexts
-Create a context indicating an approximate interval of resources
-
-\fn void starpu_sched_ctx_register_close_callback(unsigned sched_ctx_id, void (*close_callback)(unsigned sched_ctx_id, void* args), void *args)
-\ingroup API_Scheduling_Contexts
-Execute the callback whenever the last task of the context finished executing, it is called with the parameters \p sched_ctx and any other parameter needed
-by the application (packed in \p args)
-
-\fn void starpu_sched_ctx_add_workers(int *workerids_ctx, unsigned nworkers_ctx, unsigned sched_ctx_id)
-\ingroup API_Scheduling_Contexts
-Add dynamically the workers in \p workerids_ctx to the
-context \p sched_ctx_id. The last argument cannot be greater than
-::STARPU_NMAX_SCHED_CTXS.
-
-\fn void starpu_sched_ctx_remove_workers(int *workerids_ctx, unsigned nworkers_ctx, unsigned sched_ctx_id)
-\ingroup API_Scheduling_Contexts
-Remove the workers in \p workerids_ctx from the context
-\p sched_ctx_id. The last argument cannot be greater than
-::STARPU_NMAX_SCHED_CTXS.
-
-\fn void starpu_sched_ctx_display_workers(unsigned sched_ctx_id, FILE *f)
-\ingroup API_Scheduling_Contexts
-Print on the file \p f the worker names belonging to the context \p sched_ctx_id
-
-\fn void starpu_sched_ctx_delete(unsigned sched_ctx_id)
-\ingroup API_Scheduling_Contexts
-Delete scheduling context \p sched_ctx_id and transfer remaining
-workers to the inheritor scheduling context.
-
-\fn void starpu_sched_ctx_set_inheritor(unsigned sched_ctx_id, unsigned inheritor)
-\ingroup API_Scheduling_Contexts
-Indicate that the context \p inheritor will inherit the resources of the context \p sched_ctx_id when \p sched_ctx_id will be deleted.
-
-\fn void starpu_sched_ctx_set_context(unsigned *sched_ctx_id)
-\ingroup API_Scheduling_Contexts
-Set the scheduling context the subsequent tasks will be submitted to
-
-\fn unsigned starpu_sched_ctx_get_context(void)
-\ingroup API_Scheduling_Contexts
-Return the scheduling context the tasks are currently submitted to,
-or ::STARPU_NMAX_SCHED_CTXS if no default context has been defined
-by calling the function starpu_sched_ctx_set_context().
-
-\fn void starpu_sched_ctx_stop_task_submission(void)
-\ingroup API_Scheduling_Contexts
-Stop submitting tasks from the empty context list until the next time
-the context has time to check the empty context list
-
-\fn void starpu_sched_ctx_finished_submit(unsigned sched_ctx_id)
-\ingroup API_Scheduling_Contexts
-Indicate starpu that the application finished submitting to this
-context in order to move the workers to the inheritor as soon as
-possible.
-
-\fn unsigned starpu_sched_ctx_get_workers_list(unsigned sched_ctx_id, int **workerids)
-\ingroup API_Scheduling_Contexts
-Return the list of workers in the array \p workerids, the return value is the
-number of workers. The user should free the \p workerids table after finishing
-using it (it is allocated inside the function with the proper size)
-
-\fn unsigned starpu_sched_ctx_get_workers_list_raw(unsigned sched_ctx_id, int **workerids)
-\ingroup API_Scheduling_Contexts
-Return the list of workers in the array \p workerids, the return value is the
-number of workers. This list is provided in raw order, i.e. not sorted by tree or list order,
-and the user should not free the \p workerids table.
-This function is thus much less costly than starpu_sched_ctx_get_workers_list().
-
-\fn unsigned starpu_sched_ctx_get_nworkers(unsigned sched_ctx_id)
-\ingroup API_Scheduling_Contexts
-Return the number of workers managed by the specified context
-(Usually needed to verify if it manages any workers or if it should be
-blocked)
-
-\fn unsigned starpu_sched_ctx_get_nshared_workers(unsigned sched_ctx_id, unsigned sched_ctx_id2)
-\ingroup API_Scheduling_Contexts
-Return the number of workers shared by two contexts.
-
-\fn unsigned starpu_sched_ctx_contains_worker(int workerid, unsigned sched_ctx_id)
-\ingroup API_Scheduling_Contexts
-Return 1 if the worker belongs to the context and 0 otherwise
-
-\fn unsigned starpu_sched_ctx_worker_get_id(unsigned sched_ctx_id)
-\ingroup API_Scheduling_Contexts
-Return the workerid if the worker belongs to the context and -1 otherwise.
-If the thread calling this function is not a worker the function returns -1
-as it calls the function starpu_worker_get_id().
-
-\fn unsigned starpu_sched_ctx_overlapping_ctxs_on_worker(int workerid)
-\ingroup API_Scheduling_Contexts
-Check if a worker is shared between several contexts
-
-@name Scheduling Context Priorities
-\ingroup API_Scheduling_Contexts
-
-\def STARPU_MIN_PRIO
-\ingroup API_Scheduling_Contexts
-Provided for legacy reasons.
-
-\def STARPU_MAX_PRIO
-\ingroup API_Scheduling_Contexts
-Provided for legacy reasons.
-
-\def STARPU_DEFAULT_PRIO
-\ingroup API_Scheduling_Contexts
-By convention, the default priority level should be 0 so that we can
-statically allocate tasks with a default priority.
-
-\fn int starpu_sched_ctx_set_min_priority(unsigned sched_ctx_id, int min_prio)
-\ingroup API_Scheduling_Contexts
-Define the minimum task priority level supported by the scheduling
-policy of the given scheduler context. The default minimum priority
-level is the same as the default priority level which is 0 by
-convention. The application may access that value by calling the function
-starpu_sched_ctx_get_min_priority(). This function should only
-be called from the initialization method of the scheduling policy, and
-should not be used directly from the application.
-
-\fn int starpu_sched_ctx_set_max_priority(unsigned sched_ctx_id, int max_prio)
-\ingroup API_Scheduling_Contexts
-Define the maximum priority level supported by the scheduling policy
-of the given scheduler context. The default maximum priority level is
-1. The application may access that value by calling the
-starpu_sched_ctx_get_max_priority function. This function should only
-be called from the initialization method of the scheduling policy, and
-should not be used directly from the application.
-
-\fn int starpu_sched_ctx_get_min_priority(unsigned sched_ctx_id)
-\ingroup API_Scheduling_Contexts
-Return the current minimum priority level supported by the scheduling
-policy of the given scheduler context.
-
-\fn int starpu_sched_ctx_get_max_priority(unsigned sched_ctx_id)
-\ingroup API_Scheduling_Contexts
-Return the current maximum priority level supported by the scheduling
-policy of the given scheduler context.
-
-\fn int starpu_sched_ctx_min_priority_is_set(unsigned sched_ctx_id)
-\ingroup API_Scheduling_Contexts
-todo
-
-\fn int starpu_sched_ctx_max_priority_is_set(unsigned sched_ctx_id)
-\ingroup API_Scheduling_Contexts
-todo
-
-\fn void *starpu_sched_ctx_get_user_data(unsigned sched_ctx_id)
-\ingroup API_Scheduling_Contexts
-Return the user data pointer associated to the scheduling context.
-
-@name Scheduling Context Worker Collection
-\ingroup API_Scheduling_Contexts
-
-\fn struct starpu_worker_collection *starpu_sched_ctx_create_worker_collection(unsigned sched_ctx_id, enum starpu_worker_collection_type type)
-\ingroup API_Scheduling_Contexts
-Create a worker collection of the type indicated by the last parameter
-for the context specified through the first parameter.
-
-\fn void starpu_sched_ctx_delete_worker_collection(unsigned sched_ctx_id)
-\ingroup API_Scheduling_Contexts
-Delete the worker collection of the specified scheduling context
-
-\fn struct starpu_worker_collection *starpu_sched_ctx_get_worker_collection(unsigned sched_ctx_id)
-\ingroup API_Scheduling_Contexts
-Return the worker collection managed by the indicated context
-
-@name Scheduling Context Link with Hypervisor
-\ingroup API_Scheduling_Contexts
-
-\fn void starpu_sched_ctx_set_perf_counters(unsigned sched_ctx_id, void *perf_counters)
-\ingroup API_Scheduling_Contexts
-Indicate to starpu the pointer to the performance counter
-
-\fn void starpu_sched_ctx_call_pushed_task_cb(int workerid, unsigned sched_ctx_id)
-\ingroup API_Scheduling_Contexts
-Callback that lets the scheduling policy tell the hypervisor that a
-task was pushed on a worker
-
-\fn void starpu_sched_ctx_notify_hypervisor_exists(void)
-\ingroup API_Scheduling_Contexts
-Allow the hypervisor to let starpu know he's initialised
-
-\fn unsigned starpu_sched_ctx_check_if_hypervisor_exists(void)
-\ingroup API_Scheduling_Contexts
-Ask starpu if he is informed if the hypervisor is initialised
-
-\fn void starpu_sched_ctx_set_policy_data(unsigned sched_ctx_id, void *policy_data)
-\ingroup API_Scheduling_Contexts
-Allocate the scheduling policy data (private information of the scheduler like queues, variables,
-additional condition variables) the context
-
-\fn void *starpu_sched_ctx_get_policy_data(unsigned sched_ctx_id)
-\ingroup API_Scheduling_Contexts
-Return the scheduling policy data (private information of the scheduler) of the contexts previously
-assigned to.
-
-\fn void *starpu_sched_ctx_exec_parallel_code(void* (*func)(void*), void *param, unsigned sched_ctx_id)
-\ingroup API_Scheduling_Contexts
-Execute any parallel code on the workers of the sched_ctx (workers are blocked)
-
-\fn int starpu_sched_ctx_get_nready_tasks(unsigned sched_ctx_id)
-\ingroup API_Scheduling_Contexts
-todo
-
-\fn double starpu_sched_ctx_get_nready_flops(unsigned sched_ctx_id)
-\ingroup API_Scheduling_Contexts
-todo
-
 */

doc/doxygen/chapters/api/scheduling_policy.doxy

@@ -16,287 +16,11 @@
  * See the GNU Lesser General Public License in COPYING.LGPL for more details.
  */
 
-/*! \defgroup API_Scheduling_Policy Scheduling Policy
-
-\brief TODO. While StarPU comes with a variety of scheduling policies
-(see \ref TaskSchedulingPolicy), it may sometimes be desirable to
-implement custom policies to address specific problems. The API
-described below allows users to write their own scheduling policy.
+/*! \ingroup API_Scheduling_Policy Scheduling Policy
 
 \def STARPU_MAXIMPLEMENTATIONS
 \ingroup API_Scheduling_Policy
 Define the maximum number of implementations per architecture. The default value can be modified at
 configure by using the option \ref enable-maximplementations "--enable-maximplementations".
 
-\struct starpu_sched_policy
-\ingroup API_Scheduling_Policy
-Contain all the methods that implement a
-scheduling policy. An application may specify which scheduling
-strategy in the field starpu_conf::sched_policy passed to the function
-starpu_init().
-
-For each task going through the scheduler, the following methods get called in the given order:
-
-<ul>
-<li>starpu_sched_policy::submit_hook when the task is submitted</li>
-<li>starpu_sched_policy::push_task when the task becomes ready. The scheduler is here <b>given</b> the task</li>
-<li>starpu_sched_policy::pop_task when the worker is idle. The scheduler here <b>gives</b> back the task to the core. It must not access this task any more</li>
-<li>starpu_sched_policy::pre_exec_hook right before the worker actually starts the task computation (after transferring any missing data).</li>
-<li>starpu_sched_policy::post_exec_hook right after the worker actually completes the task computation.</li>
-</ul>
-
-For each task not going through the scheduler (because starpu_task::execute_on_a_specific_worker was set), these get called:
-
-<ul>
-<li>starpu_sched_policy::submit_hook when the task is submitted</li>
-<li>starpu_sched_policy::push_task_notify when the task becomes ready. This is just a notification, the scheduler does not have to do anything about the task.</li>
-<li>starpu_sched_policy::pre_exec_hook right before the worker actually starts the task computation (after transferring any missing data).</li>
-<li>starpu_sched_policy::post_exec_hook right after the worker actually completes the task computation.</li>
-</ul>
-
-
-\var void (*starpu_sched_policy::init_sched)(unsigned sched_ctx_id)
-        Initialize the scheduling policy, called before any other method.
-\var void (*starpu_sched_policy::deinit_sched)(unsigned sched_ctx_id)
-        Cleanup the scheduling policy, called before any other method.
-\var int (*starpu_sched_policy::push_task)(struct starpu_task *)
-        Insert a task into the scheduler, called when the task becomes ready for
-        execution. This must call starpu_push_task_end() once it has effectively
-        pushed the task to a queue (to note the time when this was done in the
-        task), but before releasing mutexes (so that the task hasn't been
-        already taken by a worker).
-\var void (*starpu_sched_policy::push_task_notify)(struct starpu_task *, int workerid, int perf_workerid, unsigned sched_ctx_id)
-        Notify the scheduler that a task was pushed on a given worker.
-	This method is called when a task that was explicitly
-	assigned to a worker becomes ready and is about to be executed
-	by the worker. This method therefore permits to keep the state
-	of the scheduler coherent even when StarPU bypasses the
-	scheduling strategy.
-\var struct starpu_task *(*starpu_sched_policy::pop_task)(unsigned sched_ctx_id)
-        Get a task from the scheduler.
-        If this method returns NULL, the worker will start sleeping. If later on
-        some task are pushed for this worker, starpu_wake_worker() must be
-        called to wake the worker so it can call the pop_task() method again.
-	
-        The mutex associated to the worker is already taken when this method
-        is called. This method may release it (e.g. for scalability reasons
-        when doing work stealing), but it must acquire it again before taking
-        the decision whether to return a task or NULL, so the atomicity of
-        deciding to return NULL and making the worker actually sleep is
-        preserved. Otherwise in simgrid or blocking driver mode the worker might start
-        sleeping while a task has just been pushed for it.
-
-        If this method is defined as <c>NULL</c>, the worker will only execute
-        tasks from its local queue. In this case, the push_task method should
-        use the starpu_push_local_task method to assign tasks to the different
-        workers.
-\var struct starpu_task *(*starpu_sched_policy::pop_every_task)(unsigned sched_ctx_id)
-        Remove all available tasks from the scheduler (tasks are
-	chained by the means of the field starpu_task::prev and
-	starpu_task::next). The mutex associated to the worker is
-	already taken when this method is called. This is currently
-	not used and can be discarded.
-\var void (*starpu_sched_policy::submit_hook)(struct starpu_task *)
-        Optional field. This method is called when a task is submitted.
-\var void (*starpu_sched_policy::pre_exec_hook)(struct starpu_task *)
-        Optional field. This method is called every time a task is starting.
-\var void (*starpu_sched_policy::post_exec_hook)(struct starpu_task *)
-        Optional field. This method is called every time a task has been executed.
-\var void (*starpu_sched_policy::do_schedule)(unsigned sched_ctx_id)
-        Optional field. This method is called when it is a good time to start
-        scheduling tasks. This is notably called when the application calls
-        starpu_task_wait_for_all() or starpu_do_schedule() explicitly.
-\var void (*starpu_sched_policy::add_workers)(unsigned sched_ctx_id, int *workerids, unsigned nworkers)
-        Initialize scheduling structures corresponding to each worker used by the policy.
-\var void (*starpu_sched_policy::remove_workers)(unsigned sched_ctx_id, int *workerids, unsigned nworkers)
-        Deinitialize scheduling structures corresponding to each worker used by the policy.
-\var const char *starpu_sched_policy::policy_name
-        Optional field. Name of the policy.
-\var const char *starpu_sched_policy::policy_description
-        Optional field. Human readable description of the policy.
-
-\fn struct starpu_sched_policy **starpu_sched_get_predefined_policies()
-\ingroup API_Scheduling_Policy
-Return an <c>NULL</c>-terminated array of all the predefined scheduling
-policies.
-
-\fn void starpu_worker_get_sched_condition(int workerid, starpu_pthread_mutex_t **sched_mutex, starpu_pthread_cond_t **sched_cond)
-\ingroup API_Scheduling_Policy
-When there is no available task for a worker, StarPU blocks this
-worker on a condition variable. This function specifies which
-condition variable (and the associated mutex) should be used to block
-(and to wake up) a worker. Note that multiple workers may use the same
-condition variable. For instance, in the case of a scheduling strategy
-with a single task queue, the same condition variable would be used to
-block and wake up all workers.
-
-\fn int starpu_wake_worker_no_relax(int workerid)
-\ingroup API_Scheduling_Policy
-Must be called to wake up a worker that is sleeping on the cond.
-Return 0 whenever the worker is not in a sleeping state or has the
-state_keep_awake flag on.
-
-\fn int starpu_wake_worker_locked(int workerid)
-\ingroup API_Scheduling_Policy
-Version of starpu_wake_worker_no_relax() which assumes that the sched
-mutex is locked
-
-\fn int starpu_sched_set_min_priority(int min_prio)
-\ingroup API_Scheduling_Policy
-TODO: check if this is correct
-Define the minimum task priority level supported by the scheduling
-policy. The default minimum priority level is the same as the default
-priority level which is 0 by convention. The application may access
-that value by calling the function starpu_sched_get_min_priority().
-This function should only be called from the initialization method of
-the scheduling policy, and should not be used directly from the
-application.
-
-\fn int starpu_sched_set_max_priority(int max_prio)
-\ingroup API_Scheduling_Policy
-TODO: check if this is correct
-Define the maximum priority level supported by the scheduling policy.
-The default maximum priority level is 1. The application may access
-that value by calling the function starpu_sched_get_max_priority().
-This function should only be called from the initialization method of
-the scheduling policy, and should not be used directly from the
-application.
-
-\fn int starpu_sched_get_min_priority(void)
-\ingroup API_Scheduling_Policy
-TODO: check if this is correct
-Return the current minimum priority level supported by the scheduling
-policy
-
-\fn int starpu_sched_get_max_priority(void)
-\ingroup API_Scheduling_Policy
-TODO: check if this is correct
-Return the current maximum priority level supported by the scheduling
-policy
-
-\fn int starpu_push_local_task(int workerid, struct starpu_task *task, int back)
-\ingroup API_Scheduling_Policy
-The scheduling policy may put tasks directly into a worker’s local
-queue so that it is not always necessary to create its own queue when
-the local queue is sufficient. If \p back is not 0, \p task is put
-at the back of the queue where the worker will pop tasks first.
-Setting \p back to 0 therefore ensures a FIFO ordering.
-
-\fn int starpu_push_task_end(struct starpu_task *task)
-\ingroup API_Scheduling_Policy
-Must be called by a scheduler to notify that the given
-task has just been pushed.
-
-\fn int starpu_worker_can_execute_task(unsigned workerid, struct starpu_task *task, unsigned nimpl)
-\ingroup API_Scheduling_Policy
-Check if the worker specified by workerid can execute the codelet.
-Schedulers need to call it before assigning a task to a worker,
-otherwise the task may fail to execute.
-
-\fn int starpu_worker_can_execute_task_impl(unsigned workerid, struct starpu_task *task, unsigned *impl_mask)
-\ingroup API_Scheduling_Policy
-Check if the worker specified by workerid can execute the codelet and returns
-which implementation numbers can be used.
-Schedulers need to call it before assigning a task to a worker,
-otherwise the task may fail to execute.
-This should be preferred rather than calling starpu_worker_can_execute_task for
-each and every implementation. It can also be used with <c>impl_mask == NULL</c> to
-check for at least one implementation without determining which.
-
-\fn int starpu_worker_can_execute_task_first_impl(unsigned workerid, struct starpu_task *task, unsigned *nimpl)
-\ingroup API_Scheduling_Policy
-Check if the worker specified by workerid can execute the codelet and returns
-the first implementation which can be used.
-Schedulers need to call it before assigning a task to a worker,
-otherwise the task may fail to execute.
-This should be preferred rather than calling starpu_worker_can_execute_task for
-each and every implementation. It can also be used with <c>impl_mask == NULL</c> to
-check for at least one implementation without determining which.
-
-\fn uint32_t starpu_task_footprint(struct starpu_perfmodel *model, struct starpu_task *task, struct starpu_perfmodel_arch *arch, unsigned nimpl)
-\ingroup API_Scheduling_Policy
-Return the footprint for a given task, taking into account user-provided
-perfmodel footprint or size_base functions.
-
-\fn uint32_t starpu_task_data_footprint(struct starpu_task *task)
-\ingroup API_Scheduling_Policy
-Return the raw footprint for the data of a given task (without taking into account user-provided functions).
-
-\fn double starpu_task_expected_length(struct starpu_task *task, struct starpu_perfmodel_arch *arch, unsigned nimpl)
-\ingroup API_Scheduling_Policy
-Return expected task duration in micro-seconds.
-
-\fn double starpu_worker_get_relative_speedup(struct starpu_perfmodel_arch *perf_arch)
-\ingroup API_Scheduling_Policy
-Return an estimated speedup factor relative to CPU speed
-
-\fn double starpu_task_expected_data_transfer_time(unsigned memory_node, struct starpu_task *task)
-\ingroup API_Scheduling_Policy
-Return expected data transfer time in micro-seconds for the given \p
-memory_node. Prefer using starpu_task_expected_data_transfer_time_for() which is
-more precise.
-
-\fn double starpu_task_expected_data_transfer_time_for(struct starpu_task *task, unsigned worker)
-\ingroup API_Scheduling_Policy
-Return expected data transfer time in micro-seconds for the given \p worker.
-
-\fn double starpu_data_expected_transfer_time(starpu_data_handle_t handle, unsigned memory_node, enum starpu_data_access_mode mode)
-\ingroup API_Scheduling_Policy
-Predict the transfer time (in micro-seconds) to move \p handle to a memory node
-
-\fn double starpu_task_expected_energy(struct starpu_task *task, struct starpu_perfmodel_arch *arch, unsigned nimpl)
-\ingroup API_Scheduling_Policy
-Return expected energy consumption in J
-
-\fn double starpu_task_expected_conversion_time(struct starpu_task *task, struct starpu_perfmodel_arch *arch, unsigned nimpl)
-\ingroup API_Scheduling_Policy
-Return expected conversion time in ms (multiformat interface only)
-
-\fn int starpu_get_prefetch_flag(void)
-\ingroup API_Scheduling_Policy
-Whether \ref STARPU_PREFETCH was set
-
-\fn int starpu_prefetch_task_input_on_node(struct starpu_task *task, unsigned node)
-\ingroup API_Scheduling_Policy
-Prefetch data for a given p task on a given p node
-
-\fn int starpu_prefetch_task_input_on_node_prio(struct starpu_task *task, unsigned node, int prio)
-\ingroup API_Scheduling_Policy
-Prefetch data for a given p task on a given p node with a given priority
-
-\fn int starpu_idle_prefetch_task_input_on_node(struct starpu_task *task, unsigned node)
-\ingroup API_Scheduling_Policy
-Prefetch data for a given p task on a given p node when the bus is idle
-
-\fn int starpu_idle_prefetch_task_input_on_node_prio(struct starpu_task *task, unsigned node, int prio)
-\ingroup API_Scheduling_Policy
-Prefetch data for a given p task on a given p node when the bus is idle with a given priority
-
-\fn int starpu_prefetch_task_input_for(struct starpu_task *task, unsigned worker)
-\ingroup API_Scheduling_Policy
-Prefetch data for a given p task on a given p worker
-
-\fn int starpu_prefetch_task_input_for_prio(struct starpu_task *task, unsigned worker, int prio)
-\ingroup API_Scheduling_Policy
-Prefetch data for a given p task on a given p worker with a given priority
-
-\fn int starpu_idle_prefetch_task_input_for(struct starpu_task *task, unsigned worker)
-\ingroup API_Scheduling_Policy
-Prefetch data for a given p task on a given p worker when the bus is idle
-
-\fn int starpu_idle_prefetch_task_input_for_prio(struct starpu_task *task, unsigned worker, int prio)
-\ingroup API_Scheduling_Policy
-Prefetch data for a given p task on a given p worker when the bus is idle with a given priority
-
-\fn void starpu_task_notify_ready_soon_register(starpu_notify_ready_soon_func f, void *data);
-\ingroup API_Scheduling_Policy
-Register a callback to be called when it is determined when a task will be ready
-an estimated amount of time from now, because its last dependency has just
-started and we know how long it will take.
-
-\fn void starpu_sched_ctx_worker_shares_tasks_lists(int workerid, int sched_ctx_id)
-\ingroup API_Scheduling_Policy
-The scheduling policies indicates if the worker may pop tasks from the list of other workers
-or if there is a central list with task for all the workers
-
 */

doc/doxygen/chapters/api/standard_memory_library.doxy

@@ -1,194 +0,0 @@
-/* StarPU --- Runtime system for heterogeneous multicore architectures.
- *
- * Copyright (C) 2010-2013,2015-2017                      CNRS
- * Copyright (C) 2009-2011,2014-2017,2019                 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_Standard_Memory_Library Standard Memory Library
-
-\def starpu_ssize_t
-\ingroup API_Standard_Memory_Library
-todo
-
-\def starpu_data_malloc_pinned_if_possible
-\ingroup API_Standard_Memory_Library
-\deprecated
-Equivalent to starpu_malloc(). This macro is provided to avoid breaking old codes.
-
-\def starpu_data_free_pinned_if_possible
-\ingroup API_Standard_Memory_Library
-\deprecated
-Equivalent to starpu_free(). This macro is provided to avoid breaking old codes.
-
-\def STARPU_MALLOC_PINNED
-\ingroup API_Standard_Memory_Library
-Value passed to the function starpu_malloc_flags() to indicate the memory allocation should be pinned.
-
-\def STARPU_MALLOC_COUNT
-\ingroup API_Standard_Memory_Library
-Value passed to the function starpu_malloc_flags() to indicate
-the memory allocation should be in the limit defined by the
-environment variables \ref STARPU_LIMIT_CUDA_devid_MEM,
-\ref STARPU_LIMIT_CUDA_MEM, \ref STARPU_LIMIT_OPENCL_devid_MEM,
-\ref STARPU_LIMIT_OPENCL_MEM and \ref STARPU_LIMIT_CPU_MEM (see
-Section \ref HowToLimitMemoryPerNode).
-If no memory is available, it tries to reclaim memory from StarPU.
-Memory allocated this way needs to be freed by calling the function
-starpu_free_flags() with the same flag.
-
-\def STARPU_MALLOC_NORECLAIM
-\ingroup API_Standard_Memory_Library
-Value passed to the function starpu_malloc_flags() along ::STARPU_MALLOC_COUNT
-to indicate that while the memory allocation should be kept in the limits
-defined for ::STARPU_MALLOC_COUNT, no reclaiming should be performed by
-starpu_malloc_flags() itself, thus potentially overflowing the
-memory node a bit. StarPU will reclaim memory after next task termination,
-according to the \ref STARPU_MINIMUM_AVAILABLE_MEM, \ref STARPU_TARGET_AVAILABLE_MEM,
-\ref STARPU_MINIMUM_CLEAN_BUFFERS, and \ref STARPU_TARGET_CLEAN_BUFFERS
-environment variables. If ::STARPU_MEMORY_WAIT is set, no overflowing will happen,
-starpu_malloc_flags() will wait for other eviction mechanisms to release enough memory.
-
-\def STARPU_MALLOC_SIMULATION_FOLDED
-\ingroup API_Standard_Memory_Library
-Value passed to the function starpu_malloc_flags() to indicate that when
-StarPU is using simgrid, the allocation can be "folded", i.e. a memory area is
-allocated, but its content is actually a replicate of the same memory area, to
-avoid having to actually allocate that much memory . This thus allows to have a
-memory area that does not actually consumes memory, to which one can read from
-and write to normally, but get bogus values.
-
-\fn int starpu_malloc_flags(void **A, size_t dim, int flags)
-\ingroup API_Standard_Memory_Library
-Perform a memory allocation based on the constraints defined
-by the given flag.
-
-\fn void starpu_malloc_set_align(size_t align)
-\ingroup API_Standard_Memory_Library
-Set an alignment constraints for starpu_malloc()
-allocations. \p align must be a power of two. This is for instance called
-automatically by the OpenCL driver to specify its own alignment
-constraints.
-
-\fn int starpu_malloc(void **A, size_t dim)
-\ingroup API_Standard_Memory_Library
-Allocate data of the given size \p dim in main memory, and
-return the pointer to the allocated data through \p A.
-It will also try to pin it in CUDA or OpenCL, so that data transfers
-from this buffer can be asynchronous, and thus permit data transfer
-and computation overlapping. The allocated buffer must be freed thanks
-to the starpu_free() function.
-
-\fn int starpu_free(void *A)
-\ingroup API_Standard_Memory_Library
-Free memory which has previously been allocated with starpu_malloc().
-
-\fn int starpu_free_flags(void *A, size_t dim, int flags)
-\ingroup API_Standard_Memory_Library
-Free memory by specifying its size. The given
-flags should be consistent with the ones given to starpu_malloc_flags()
-when allocating the memory.
-
-\fn void starpu_malloc_set_hooks(starpu_malloc_hook malloc_hook, starpu_free_hook free_hook)
-\ingroup API_Standard_Memory_Library
-Sets allocation functions to be used by StarPU. By default, StarPU will use
-\c malloc() (or \c cudaHostAlloc() if CUDA GPUs are used) for all its data
-handle allocations. The application can specify another allocation primitive
-by calling this. The malloc_hook should pass the allocated pointer through
-the \c A parameter, and return 0 on success. On allocation failure, it should
-return -ENOMEM. The \c flags parameter contains STARPU_MALLOC_PINNED if the
-memory should be pinned by the hook for GPU transfer efficiency. The hook
-can use starpu_memory_pin() to achieve this.  The \c dst_node parameter
-is the starpu memory node, one can convert it to an hwloc logical id with
-starpu_memory_nodes_numa_id_to_hwloclogid() or to an OS NUMA number with
-starpu_memory_nodes_numa_devid_to_id().
-
-\fn int starpu_memory_pin(void *addr, size_t size)
-\ingroup API_Standard_Memory_Library
-Pin the given memory area, so that CPU-GPU transfers can be done
-asynchronously with DMAs. The memory must be unpinned with
-starpu_memory_unpin() before being freed. Returns 0 on success, -1 on error.
-
-\fn int starpu_memory_unpin(void *addr, size_t size)
-\ingroup API_Standard_Memory_Library
-Unpin the given memory area previously pinned with
-starpu_memory_pin(). Returns 0 on success, -1 on error.
-
-\fn ssize_t starpu_memory_get_total(unsigned node)
-\ingroup API_Standard_Memory_Library
-If a memory limit is defined on the given node (see Section
-\ref HowToLimitMemoryPerNode), return the amount of total memory
-on the node. Otherwise return -1.
-
-\fn ssize_t starpu_memory_get_total_all_nodes()
-\ingroup API_Standard_Memory_Library
-Return the amount of total memory on all memory nodes for whose a memory limit
-is defined (see Section \ref HowToLimitMemoryPerNode).
-
-\fn ssize_t starpu_memory_get_available(unsigned node)
-\ingroup API_Standard_Memory_Library
-If a memory limit is defined on the given node (see Section
-\ref HowToLimitMemoryPerNode), return the amount of available memory
-on the node. Otherwise return -1.
-
-\fn ssize_t starpu_memory_get_available_all_nodes()
-\ingroup API_Standard_Memory_Library
-Return the amount of available memory on all memory nodes for whose a memory limit
-is defined (see Section \ref HowToLimitMemoryPerNode).
-
-\fn int starpu_memory_allocate(unsigned node, size_t size, int flags)
-\ingroup API_Standard_Memory_Library
-If a memory limit is defined on the given node (see Section
-\ref HowToLimitMemoryPerNode), try to allocate some of it. This does not actually
-allocate memory, but only accounts for it. This can be useful when the
-application allocates data another way, but want StarPU to be aware of the
-allocation size e.g. for memory reclaiming.
-By default, the function returns <c>-ENOMEM</c> if there is not enough room on
-the given node. \p flags can be either ::STARPU_MEMORY_WAIT or
-::STARPU_MEMORY_OVERFLOW to change this.
-
-\fn void starpu_memory_deallocate(unsigned node, size_t size)
-\ingroup API_Standard_Memory_Library
-If a memory limit is defined on the given node (see Section
-\ref HowToLimitMemoryPerNode), free some of it. This does not actually free memory,
-but only accounts for it, like starpu_memory_allocate(). The amount does not
-have to be exactly the same as what was passed to starpu_memory_allocate(),
-only the eventual amount needs to be the same, i.e. one call to
-starpu_memory_allocate() can be followed by several calls to
-starpu_memory_deallocate() to declare the deallocation piece by piece.
-
-\fn void starpu_memory_wait_available(unsigned node, size_t size)
-\ingroup API_Standard_Memory_Library
-If a memory limit is defined on the given
-node (see Section \ref HowToLimitMemoryPerNode), this will wait for \p size
-bytes to become available on \p node. Of course, since another thread may be
-allocating memory concurrently, this does not necessarily mean that this amount
-will be actually available, just that it was reached. To atomically wait for
-some amount of memory and reserve it, starpu_memory_allocate() should be used
-with the ::STARPU_MEMORY_WAIT flag.
-
-\def STARPU_MEMORY_WAIT
-\ingroup API_Standard_Memory_Library
-Value passed to starpu_memory_allocate() to specify that the function should
-wait for the requested amount of memory to become available, and atomically
-allocate it.
-
-\def STARPU_MEMORY_OVERFLOW
-\ingroup API_Standard_Memory_Library
-Value passed to starpu_memory_allocate() to specify that the function should
-allocate the amount of memory, even if that means overflowing the total size of
-the memory node.
-
-
-*/

doc/doxygen/chapters/api/task_bundles.doxy

@@ -1,69 +0,0 @@
-/* StarPU --- Runtime system for heterogeneous multicore architectures.
- *
- * Copyright (C) 2010-2013,2015,2017                      CNRS
- * Copyright (C) 2009-2011,2014,2016                      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_Task_Bundles Task Bundles
-
-\typedef starpu_task_bundle_t
-\ingroup API_Task_Bundles
-Opaque structure describing a list of tasks that should be scheduled
-on the same worker whenever it’s possible. It must be considered as a
-hint given to the scheduler as there is no guarantee that they will be
-executed on the same worker.
-
-\fn void starpu_task_bundle_create(starpu_task_bundle_t *bundle)
-\ingroup API_Task_Bundles
-Factory function creating and initializing \p bundle, when the call
-returns, memory needed is allocated and \p bundle is ready to use.
-
-\fn int starpu_task_bundle_insert(starpu_task_bundle_t bundle, struct starpu_task *task)
-\ingroup API_Task_Bundles
-Insert \p task in \p bundle. Until \p task is removed from \p bundle
-its expected length and data transfer time will be considered along
-those of the other tasks of bundle. This function must not be called
-if \p bundle is already closed and/or \p task is already submitted.
-On success, it returns 0. There are two cases of error : if \p bundle
-is already closed it returns <c>-EPERM</c>, if \p task was already
-submitted it returns <c>-EINVAL</c>.
-
-\fn int starpu_task_bundle_remove(starpu_task_bundle_t bundle, struct starpu_task *task)
-\ingroup API_Task_Bundles
-Remove \p task from \p bundle. Of course \p task must have been
-previously inserted in \p bundle. This function must not be called if
-\p bundle is already closed and/or \p task is already submitted. Doing
-so would result in undefined behaviour. On success, it returns 0. If
-\p bundle is already closed it returns <c>-ENOENT</c>.
-
-\fn void starpu_task_bundle_close(starpu_task_bundle_t bundle)
-\ingroup API_Task_Bundles
-Inform the runtime that the user will not modify \p bundle anymore, it
-means no more inserting or removing task. Thus the runtime can destroy
-it when possible.
-
-\fn double starpu_task_bundle_expected_length(starpu_task_bundle_t bundle, struct starpu_perfmodel_arch *arch, unsigned nimpl)
-\ingroup API_Task_Bundles
-Return the expected duration of \p bundle in micro-seconds.
-
-\fn double starpu_task_bundle_expected_energy(starpu_task_bundle_t bundle, struct starpu_perfmodel_arch *arch, unsigned nimpl)
-\ingroup API_Task_Bundles
-Return the expected energy consumption of \p bundle in J.
-
-\fn double starpu_task_bundle_expected_data_transfer_time(starpu_task_bundle_t bundle, unsigned memory_node)
-\ingroup API_Task_Bundles
-Return the time (in micro-seconds) expected to transfer all data used within \p bundle.
-
-*/

doc/doxygen/chapters/api/task_lists.doxy

@@ -1,82 +0,0 @@
-/* StarPU --- Runtime system for heterogeneous multicore architectures.
- *
- * Copyright (C) 2010-2017                                CNRS
- * Copyright (C) 2009-2011,2014,2016                      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_Task_Lists Task Lists
-
-\struct starpu_task_list
-Stores a double-chained list of tasks
-\ingroup API_Task_Lists
-\var struct starpu_task *starpu_task_list::head
-    head of the list
-\var struct starpu_task *starpu_task_list::tail
-    tail of the list
-
-\fn void starpu_task_list_init(struct starpu_task_list *list)
-\ingroup API_Task_Lists
-Initialize a list structure
-
-\fn void starpu_task_list_push_front(struct starpu_task_list *list, struct starpu_task *task)
-\ingroup API_Task_Lists
-Push \p task at the front of \p list
-
-\fn void starpu_task_list_push_back(struct starpu_task_list *list, struct starpu_task *task)
-\ingroup API_Task_Lists
-Push \p task at the back of \p list
-
-\fn struct starpu_task *starpu_task_list_front(const struct starpu_task_list *list)
-\ingroup API_Task_Lists
-Get the front of \p list (without removing it)
-
-\fn struct starpu_task *starpu_task_list_back(const struct starpu_task_list *list)
-\ingroup API_Task_Lists
-Get the back of \p list (without removing it)
-
-\fn int starpu_task_list_empty(const struct starpu_task_list *list)
-\ingroup API_Task_Lists
-Test if \p list is empty
-
-\fn void starpu_task_list_erase(struct starpu_task_list *list, struct starpu_task *task)
-\ingroup API_Task_Lists
-Remove \p task from \p list
-
-\fn struct starpu_task *starpu_task_list_pop_front(struct starpu_task_list *list)
-\ingroup API_Task_Lists
-Remove the element at the front of \p list
-
-\fn struct starpu_task *starpu_task_list_pop_back(struct starpu_task_list *list)
-\ingroup API_Task_Lists
-Remove the element at the back of \p list
-
-\fn struct starpu_task *starpu_task_list_begin(const struct starpu_task_list *list)
-\ingroup API_Task_Lists
-Get the first task of \p list.
-
-\fn struct starpu_task *starpu_task_list_end(const struct starpu_task_list *list)
-\ingroup API_Task_Lists
-Get the end of \p list.
-
-\fn struct starpu_task *starpu_task_list_next(const struct starpu_task *task)
-\ingroup API_Task_Lists
-Get the next task of \p list. This is not erase-safe.
-
-\fn int starpu_task_list_ismember(const struct starpu_task_list *list, const struct starpu_task *look)
-\ingroup API_Task_Lists
-Test whether the given task \p look is contained in the \p list.
-
-*/
-

doc/doxygen/chapters/api/top.doxy

@@ -1,207 +0,0 @@
-/* StarPU --- Runtime system for heterogeneous multicore architectures.
- *
- * Copyright (C) 2010-2015,2017                           CNRS
- * Copyright (C) 2009-2011,2014                           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_StarPUTop_Interface StarPU-Top Interface
-
-\enum starpu_top_data_type
-\ingroup API_StarPUTop_Interface
-StarPU-Top Data type
-\var starpu_top_data_type::STARPU_TOP_DATA_BOOLEAN
-    todo
-\var starpu_top_data_type::STARPU_TOP_DATA_INTEGER
-    todo
-\var starpu_top_data_type::STARPU_TOP_DATA_FLOAT
-    todo
-
-\enum starpu_top_param_type
-\ingroup API_StarPUTop_Interface
-StarPU-Top Parameter type
-\var starpu_top_param_type::STARPU_TOP_PARAM_BOOLEAN
-    todo
-\var starpu_top_param_type::STARPU_TOP_PARAM_INTEGER
-    todo
-\var starpu_top_param_type::STARPU_TOP_PARAM_FLOAT
-    todo
-\var starpu_top_param_type::STARPU_TOP_PARAM_ENUM
-    todo
-
-\enum starpu_top_message_type
-\ingroup API_StarPUTop_Interface
-StarPU-Top Message type
-\var starpu_top_message_type::TOP_TYPE_GO
-    todo
-\var starpu_top_message_type::TOP_TYPE_SET
-    todo
-\var starpu_top_message_type::TOP_TYPE_CONTINUE
-    todo
-\var starpu_top_message_type::TOP_TYPE_ENABLE
-    todo
-\var starpu_top_message_type::TOP_TYPE_DISABLE
-    todo
-\var starpu_top_message_type::TOP_TYPE_DEBUG
-    todo
-\var starpu_top_message_type::TOP_TYPE_UNKNOW
-    todo
-
-\struct starpu_top_data
-todo
-\ingroup API_StarPUTop_Interface
-\var unsigned int starpu_top_data::id
-    todo
-\var const char *starpu_top_data::name
-    todo
-\var int starpu_top_data::int_min_value
-    todo
-\var int starpu_top_data::int_max_value
-    todo
-\var double starpu_top_data::double_min_value
-    todo
-\var double starpu_top_data::double_max_value
-    todo
-\var int starpu_top_data::active
-    todo
-\var enum starpu_top_data_type starpu_top_data::type
-    todo
-\var struct starpu_top_data *starpu_top_data::next
-    todo
-
-\struct starpu_top_param
-todo
-\ingroup API_StarPUTop_Interface
-\var unsigned int starpu_top_param::id
-    todo
-\var const char *starpu_top_param::name
-    todo
-\var enum starpu_top_param_type starpu_top_param::type
-    todo
-\var void *starpu_top_param::value
-    todo
-\var char **starpu_top_param::enum_values
-    only for enum type can be <c>NULL</c>
-\var int starpu_top_param::nb_values
-    todo
-\var void (*starpu_top_param::callback)(struct starpu_top_param*)
-    todo
-\var int starpu_top_param::int_min_value
-    only for integer type
-\var int starpu_top_param::int_max_value
-    todo
-\var double starpu_top_param::double_min_value
-    only for double type
-\var double starpu_top_param::double_max_value
-    todo
-\var struct starpu_top_param *starpu_top_param::next
-    todo
-
-@name Functions to call before the initialisation
-\ingroup API_StarPUTop_Interface
-
-\fn struct starpu_top_data *starpu_top_add_data_boolean(const char *data_name, int active)
-\ingroup API_StarPUTop_Interface
-Register a data named \p data_name of type boolean.
-If \p active is 0, the value will NOT be displayed to users.
-Any other value will make the value displayed.
-
-\fn struct starpu_top_data *starpu_top_add_data_integer(const char *data_name, int minimum_value, int maximum_value, int active)
-\ingroup API_StarPUTop_Interface
-Register a data named \p data_name of type integer. \p minimum_value
-and \p maximum_value will be used to define the scale in the UI.
-If \p active is 0, the value will NOT be displayed to users.
-Any other value will make the value displayed.
-
-\fn struct starpu_top_data *starpu_top_add_data_float(const char *data_name, double minimum_value, double maximum_value, int active)
-\ingroup API_StarPUTop_Interface
-Register a data named \p data_name of type float. \p minimum_value and
-\p maximum_value will be used to define the scale in the UI.
-If \p active is 0, the value will NOT be displayed to users.
-Any other value will make the value displayed.
-
-\fn struct starpu_top_param *starpu_top_register_parameter_boolean(const char *param_name, int *parameter_field, void (*callback)(struct starpu_top_param*))
-\ingroup API_StarPUTop_Interface
-Register a parameter named \p parameter_name, of type
-boolean. If not \c NULL, the \p callback function will be called when
-the parameter is modified by the UI.
-
-\fn struct starpu_top_param *starpu_top_register_parameter_float(const char *param_name, double *parameter_field, double minimum_value, double maximum_value, void (*callback)(struct starpu_top_param*))
-\ingroup API_StarPUTop_Interface
-Register a parameter named \p param_name, of type
-integer. \p minimum_value and \p maximum_value will be used to prevent
-users from setting incorrect value. If not \c NULL, the \p callback
-function will be called when the parameter is modified by the UI.
-
-\fn struct starpu_top_param *starpu_top_register_parameter_integer(const char *param_name, int *parameter_field, int minimum_value, int maximum_value, void (*callback)(struct starpu_top_param*))
-\ingroup API_StarPUTop_Interface
-Register a parameter named \p param_name, of type float.
-\p minimum_value and \p maximum_value will be used to prevent users
-from setting incorrect value. If not \c NULL, the \p callback function
-will be called when the parameter is modified by the UI.
-
-\fn struct starpu_top_param *starpu_top_register_parameter_enum(const char *param_name, int *parameter_field, char **values, int nb_values, void (*callback)(struct starpu_top_param*))
-\ingroup API_StarPUTop_Interface
-Register a parameter named \p param_name, of type enum.
-\p values and \p nb_values will be used to prevent users from setting
-incorrect value. If not \c NULL, the \p callback function will be
-called when the parameter is modified by the UI.
-
-@name Initialisation
-\ingroup API_StarPUTop_Interface
-
-\fn void starpu_top_init_and_wait(const char *server_name)
-\ingroup API_StarPUTop_Interface
-Must be called when all parameters and data have been
-registered AND initialised (for parameters). It will wait
-for a TOP to connect, send initialisation sentences, and wait for the
-GO message.
-
-@name To call after initialisation
-\ingroup API_StarPUTop_Interface
-
-\fn void starpu_top_update_parameter(const struct starpu_top_param *param)
-\ingroup API_StarPUTop_Interface
-Should be called after every modification of a parameter
-from something other than starpu_top. It notices the UI that the
-configuration has changed.
-
-\fn void starpu_top_update_data_boolean(const struct starpu_top_data *data, int value)
-\ingroup API_StarPUTop_Interface
-Update the boolean value of \p data to \p value the UI.
-
-\fn void starpu_top_update_data_integer(const struct starpu_top_data *data, int value)
-\ingroup API_StarPUTop_Interface
-Update the integer value of \p data to \p value the UI.
-
-\fn void starpu_top_update_data_float(const struct starpu_top_data *data, double value)
-\ingroup API_StarPUTop_Interface
-Update the float value of \p data to \p value the UI.
-
-\fn void starpu_top_task_prevision(struct starpu_task *task, int devid, unsigned long long start, unsigned long long end)
-\ingroup API_StarPUTop_Interface
-Notift the UI that \p task is planned to run from \p start to \p end, on computation-core.
-
-\fn void starpu_top_debug_log(const char *message)
-\ingroup API_StarPUTop_Interface
-When running in debug mode, display \p message in the UI.
-
-\fn void starpu_top_debug_lock(const char *message)
-\ingroup API_StarPUTop_Interface
-When running in debug mode, send \p message to the UI and wait for a
-continue message to return. The lock (which creates a stop-point) should be
-called only by the main thread. Calling it from more than one thread
-is not supported.
-
-*/

doc/doxygen/chapters/api/tree.doxy

@@ -1,56 +0,0 @@
-/* StarPU --- Runtime system for heterogeneous multicore architectures.
- *
- * Copyright (C) 2014-2017                                CNRS
- *
- * 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_Tree Tree
-
-\brief This section describes the tree facilities provided by StarPU.
-
-\struct starpu_tree
-\ingroup API_Tree
-\var struct starpu_tree **starpu_tree::nodes
-    todo
-\var struct starpu_tree *starpu_tree::father
-    todo
-\var int starpu_tree::arity
-    todo
-\var int starpu_tree::id
-    todo
-\var int starpu_tree::level
-    todo
-\var int starpu_tree::is_pu
-    todo
-
-\fn void starpu_tree_reset_visited(struct starpu_tree *tree, char *visited)
-\ingroup API_Tree
-todo
-
-\fn void starpu_tree_insert(struct starpu_tree *tree, int id, int level, int is_pu, int arity, struct starpu_tree *father)
-\ingroup API_Tree
-todo
-
-\fn struct starpu_tree *starpu_tree_get(struct starpu_tree *tree, int id)
-\ingroup API_Tree
-todo
-
-\fn struct starpu_tree *starpu_tree_get_neighbour(struct starpu_tree *tree, struct starpu_tree *node, char *visited, char *present)
-\ingroup API_Tree
-todo
-
-\fn void starpu_tree_free(struct starpu_tree *tree)
-\ingroup API_Tree
-todo
-
-*/

doc/doxygen/doxygen-config.cfg.in

@@ -54,6 +54,7 @@ INPUT                  = @top_srcdir@/doc/doxygen/chapters \
 			 @top_srcdir@/include/starpu_stdlib.h \
 			 @top_srcdir@/include/starpu_task_bundle.h \
 			 @top_srcdir@/include/starpu_task.h \
+			 @top_srcdir@/include/starpu_task_dep.h \
 			 @top_srcdir@/include/starpu_task_list.h \
 			 @top_srcdir@/include/starpu_task_util.h \
 			 @top_srcdir@/include/starpu_thread.h \

doc/doxygen/doxygen_filter.sh.in

@@ -1,7 +1,7 @@
 #!/bin/bash
 # StarPU --- Runtime system for heterogeneous multicore architectures.
 #
-# Copyright (C) 2013,2014,2016,2017                      CNRS
+# Copyright (C) 2013,2014,2016,2017,2019                 CNRS
 #
 # 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
@@ -19,6 +19,5 @@ if [ "$(basename $1)" == "starpufft.h" ] ; then
 else
     # the macro STARPU_DEPRECATED needs to be removed as it is not properly processed by doxygen
     # lines starting with // in the doxygen input files are considered as comments to be removed
-    sed -e 's/STARPU_DEPRECATED//' $1 | sed 's/^\/\/.*//'
+    sed -e 's/STARPU_DEPRECATED//' $1 | sed -e 's/^\/\/.*//' | sed -e 's/STARPU_TASK_LIST_INLINE//'
 fi
-

include/starpu.h

@@ -56,6 +56,7 @@ typedef INT_PTR intptr_t;
 #include <starpu_data_filters.h>
 #include <starpu_stdlib.h>
 #include <starpu_task_bundle.h>
+#include <starpu_task_dep.h>
 #include <starpu_task.h>
 #include <starpu_worker.h>
 #include <starpu_perfmodel.h>
@@ -64,6 +65,7 @@ typedef INT_PTR intptr_t;
 #include <starpu_task_list.h>
 #endif
 #include <starpu_task_util.h>
+#include <starpu_scheduler.h>
 #include <starpu_sched_ctx.h>
 #include <starpu_expert.h>
 #include <starpu_rand.h>

include/starpu_bitmap.h

@@ -19,17 +19,17 @@
 #ifndef __STARPU_BITMAP_H__
 #define __STARPU_BITMAP_H__
 
+#ifdef __cplusplus
+extern "C"
+{
+#endif
+
 /**
    @defgroup API_Bitmap Bitmap
    @brief This is the interface for the bitmap utilities provided by StarPU.
    @{
  */
 
-#ifdef __cplusplus
-extern "C"
-{
-#endif
-
 /** create a empty starpu_bitmap */
 struct starpu_bitmap *starpu_bitmap_create(void) STARPU_ATTRIBUTE_MALLOC;
 /** free \p b */
@@ -62,10 +62,10 @@ int starpu_bitmap_next(struct starpu_bitmap *b, int e);
 /** todo */
 int starpu_bitmap_has_next(struct starpu_bitmap *b, int e);
 
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif
 
-/** @} */
-
 #endif

include/starpu_bound.h

@@ -18,12 +18,6 @@
 #ifndef __STARPU_BOUND_H__
 #define __STARPU_BOUND_H__
 
-/**
-   @defgroup API_Theoretical_Lower_Bound_on_Execution_Time Theoretical Lower Bound on Execution Time
-   @brief Compute theoretical upper computation efficiency bound corresponding to some actual execution.
-   @{
-*/
-
 #include <stdio.h>
 
 #ifdef __cplusplus
@@ -32,6 +26,12 @@ extern "C"
 #endif
 
 /**
+   @defgroup API_Theoretical_Lower_Bound_on_Execution_Time Theoretical Lower Bound on Execution Time
+   @brief Compute theoretical upper computation efficiency bound corresponding to some actual execution.
+   @{
+*/
+
+/**
    Start recording tasks (resets stats). \p deps tells whether
    dependencies should be recorded too (this is quite expensive)
 */
@@ -74,10 +74,10 @@ void starpu_bound_print_mps(FILE *output);
 */
 void starpu_bound_print(FILE *output, int integer);
 
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif
 
-/** @} */
-
 #endif /* __STARPU_BOUND_H__ */

include/starpu_clusters.h

@@ -19,11 +19,6 @@
 #ifndef __STARPU_CLUSTERS_UTIL_H__
 #define __STARPU_CLUSTERS_UTIL_H__
 
-/**
-   @defgroup API_Clustering_Machine Clustering Machine
-   @{
- */
-
 #ifdef STARPU_HAVE_HWLOC
 
 #include <hwloc.h>
@@ -33,6 +28,11 @@ extern "C"
 {
 #endif
 
+/**
+   @defgroup API_Clustering_Machine Clustering Machine
+   @{
+ */
+
 #define STARPU_CLUSTER_MIN_NB			(1<<STARPU_MODE_SHIFT)
 #define STARPU_CLUSTER_MAX_NB			(2<<STARPU_MODE_SHIFT)
 #define STARPU_CLUSTER_NB			(3<<STARPU_MODE_SHIFT)
@@ -74,12 +74,12 @@ void starpu_openmp_prologue(void*);
 void starpu_gnu_openmp_mkl_prologue(void*);
 #endif /* STARPU_MKL */
 
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif
 
 #endif
 
-/** @} */
-
 #endif /* __STARPU_CLUSTERS_UTIL_H__ */

include/starpu_cublas.h

@@ -18,17 +18,17 @@
 #ifndef __STARPU_CUBLAS_H__
 #define __STARPU_CUBLAS_H__
 
-/**
-   @ingroup API_CUDA_Extensions
-   @{
- */
-
 #ifdef __cplusplus
 extern "C"
 {
 #endif
 
 /**
+   @ingroup API_CUDA_Extensions
+   @{
+ */
+
+/**
    Initialize CUBLAS on every CUDA device. The
    CUBLAS library must be initialized prior to any CUBLAS call. Calling
    starpu_cublas_init() will initialize CUBLAS on every CUDA device
@@ -53,10 +53,10 @@ void starpu_cublas_set_stream(void);
 */
 void starpu_cublas_shutdown(void);
 
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif
 
-/** @} */
-
 #endif /* __STARPU_CUBLAS_H__ */

include/starpu_cublas_v2.h

@@ -18,11 +18,6 @@
 #ifndef __STARPU_CUBLAS_V2_H__
 #define __STARPU_CUBLAS_V2_H__
 
-/**
-   @ingroup API_CUDA_Extensions
-   @{
- */
-
 #if defined STARPU_USE_CUDA && !defined STARPU_DONT_INCLUDE_CUDA_HEADERS
 
 #include <cublas_v2.h>
@@ -33,18 +28,23 @@ extern "C"
 #endif
 
 /**
+   @ingroup API_CUDA_Extensions
+   @{
+ */
+
+/**
    Return the CUSPARSE handle to be used to queue CUSPARSE kernels. It
    is properly initialized and configured for multistream by
    starpu_cusparse_init().
 */
 cublasHandle_t starpu_cublas_get_local_handle(void);
 
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif
 
 #endif
 
-/** @} */
-
 #endif /* __STARPU_CUBLAS_V2_H__ */

include/starpu_cuda.h

@@ -19,11 +19,6 @@
 #ifndef __STARPU_CUDA_H__
 #define __STARPU_CUDA_H__
 
-/**
-   @defgroup API_CUDA_Extensions CUDA Extensions
-   @{
- */
-
 #include <starpu_config.h>
 
 #if defined STARPU_USE_CUDA && !defined STARPU_DONT_INCLUDE_CUDA_HEADERS
@@ -37,6 +32,11 @@ extern "C"
 #endif
 
 /**
+   @defgroup API_CUDA_Extensions CUDA Extensions
+   @{
+ */
+
+/**
    Report a CUBLAS error.
 */
 void starpu_cublas_report_error(const char *func, const char *file, int line, int status);
@@ -93,12 +93,12 @@ int starpu_cuda_copy_async_sync(void *src_ptr, unsigned src_node, void *dst_ptr,
 */
 void starpu_cuda_set_device(unsigned devid);
 
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif
 
 #endif /* STARPU_USE_CUDA && !STARPU_DONT_INCLUDE_CUDA_HEADERS */
 
-/** @} */
-
 #endif /* __STARPU_CUDA_H__ */

include/starpu_cusparse.h

@@ -18,11 +18,6 @@
 #ifndef __STARPU_CUSPARSE_H__
 #define __STARPU_CUSPARSE_H__
 
-/**
-   @ingroup API_CUDA_Extensions
-   @{
-*/
-
 #if defined STARPU_USE_CUDA && !defined STARPU_DONT_INCLUDE_CUDA_HEADERS
 #include <cusparse.h>
 #endif
@@ -33,6 +28,11 @@ extern "C"
 #endif
 
 /**
+   @ingroup API_CUDA_Extensions
+   @{
+*/
+
+/**
    Initialize CUSPARSE on every CUDA device
    controlled by StarPU. This call blocks until CUSPARSE has been properly
    initialized on every device.
@@ -54,10 +54,10 @@ void starpu_cusparse_shutdown(void);
 cusparseHandle_t starpu_cusparse_get_local_handle(void);
 #endif
 
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif
 
-/** @} */
-
 #endif /* __STARPU_CUSPARSE_H__ */

include/starpu_data.h

@@ -19,14 +19,6 @@
 #ifndef __STARPU_DATA_H__
 #define __STARPU_DATA_H__
 
-/**
-   @defgroup API_Data_Management Data Management
-   @brief Data management facilities provided by StarPU. We show how
-   to use existing data interfaces in \ref API_Data_Interfaces, but
-   developers can design their own data interfaces if required.
-   @{
-*/
-
 #include <starpu.h>
 
 #ifdef __cplusplus
@@ -35,9 +27,12 @@ extern "C"
 #endif
 
 /**
-   This macro is used when the RAM memory node is specified.
+   @defgroup API_Data_Management Data Management
+   @brief Data management facilities provided by StarPU. We show how
+   to use existing data interfaces in \ref API_Data_Interfaces, but
+   developers can design their own data interfaces if required.
+   @{
 */
-#define STARPU_MAIN_RAM 0
 
 struct _starpu_data_state;
 /**
@@ -120,15 +115,6 @@ enum starpu_data_access_mode
 	STARPU_ACCESS_MODE_MAX=(1<<7) /**< todo */
 };
 
-/**
-   Describe a data handle along with an access mode.
-*/
-struct starpu_data_descr
-{
-	starpu_data_handle_t handle; /**< data */
-	enum starpu_data_access_mode mode; /**< access mode */
-};
-
 struct starpu_data_interface_ops;
 
 /** Set the name of the data, to be shown in various profiling tools. */
@@ -550,10 +536,10 @@ void *starpu_data_get_user_data(starpu_data_handle_t handle);
 */
 int starpu_data_cpy(starpu_data_handle_t dst_handle, starpu_data_handle_t src_handle, int asynchronous, void (*callback_func)(void*), void *callback_arg);
 
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif
 
-/** @} */
-
 #endif /* __STARPU_DATA_H__ */

include/starpu_data_filters.h

@@ -21,11 +21,6 @@
 #ifndef __STARPU_DATA_FILTERS_H__
 #define __STARPU_DATA_FILTERS_H__
 
-/**
-   @defgroup API_Data_Partition Data Partition
-   @{
-*/
-
 #include <starpu.h>
 #include <stdarg.h>
 
@@ -34,6 +29,11 @@ extern "C"
 {
 #endif
 
+/**
+   @defgroup API_Data_Partition Data Partition
+   @{
+*/
+
 struct starpu_data_interface_ops;
 
 /**
@@ -507,10 +507,10 @@ void starpu_block_filter_depth_block_shadow(void *father_interface, void *child_
 
 /** @} */
 
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif
 
-/** @} */
-
 #endif

include/starpu_data_interfaces.h

@@ -19,6 +19,23 @@
 #ifndef __STARPU_DATA_INTERFACES_H__
 #define __STARPU_DATA_INTERFACES_H__
 
+#include <starpu.h>
+
+#ifdef STARPU_USE_CUDA
+/* to use CUDA streams */
+# ifdef STARPU_DONT_INCLUDE_CUDA_HEADERS
+typedef void *starpu_cudaStream_t;
+# else
+#  include <cuda_runtime.h>
+typedef cudaStream_t starpu_cudaStream_t;
+# endif
+#endif
+
+#ifdef __cplusplus
+extern "C"
+{
+#endif
+
 /**
    @defgroup API_Data_Interfaces Data Interfaces
    @brief Data management is done at a high-level in StarPU: rather than
@@ -67,23 +84,6 @@
    @{
 */
 
-#include <starpu.h>
-
-#ifdef STARPU_USE_CUDA
-/* to use CUDA streams */
-# ifdef STARPU_DONT_INCLUDE_CUDA_HEADERS
-typedef void *starpu_cudaStream_t;
-# else
-#  include <cuda_runtime.h>
-typedef cudaStream_t starpu_cudaStream_t;
-# endif
-#endif
-
-#ifdef __cplusplus
-extern "C"
-{
-#endif
-
 /**
    Define the per-interface methods. If the
    starpu_data_copy_methods::any_to_any method is provided, it will be
@@ -1760,10 +1760,10 @@ void starpu_multiformat_data_register(starpu_data_handle_t *handle, int home_nod
 
 /** @} */
 
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif
 
-/** @} */
-
 #endif /* __STARPU_DATA_INTERFACES_H__ */

include/starpu_disk.h

@@ -20,14 +20,14 @@
 #ifndef __STARPU_DISK_H__
 #define __STARPU_DISK_H__
 
+#include <sys/types.h>
+#include <starpu_config.h>
+
 /**
    @defgroup API_Out_Of_Core Out Of Core
    @{
 */
 
-#include <sys/types.h>
-#include <starpu_config.h>
-
 /**
    Set of functions to manipulate datas on disk.
 */

include/starpu_driver.h

@@ -18,11 +18,6 @@
 #ifndef __STARPU_DRIVER_H__
 #define __STARPU_DRIVER_H__
 
-/**
-   @defgroup API_Running_Drivers Running Drivers
-   @{
-*/
-
 #include <starpu_config.h>
 #if defined(STARPU_USE_OPENCL) && !defined(__CUDACC__)
 #include <starpu_opencl.h>
@@ -34,6 +29,11 @@ extern "C"
 #endif
 
 /**
+   @defgroup API_Running_Drivers Running Drivers
+   @{
+*/
+
+/**
    structure for a driver
 */
 struct starpu_driver
@@ -93,10 +93,10 @@ int starpu_driver_run_once(struct starpu_driver *d);
 */
 int starpu_driver_deinit(struct starpu_driver *d);
 
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif
 
-/** @} */
-
 #endif /* __STARPU_DRIVER_H__ */

include/starpu_expert.h

@@ -18,17 +18,17 @@
 #ifndef __STARPU_EXPERT_H__
 #define __STARPU_EXPERT_H__
 
-/**
-   @defgroup API_Expert_Mode Expert Mode
-   @{
-*/
-
 #ifdef __cplusplus
 extern "C"
 {
 #endif
 
 /**
+   @defgroup API_Expert_Mode Expert Mode
+   @{
+*/
+
+/**
    Wake all the workers, so they can inspect data requests and task
    submissions again.
 */
@@ -47,10 +47,10 @@ void starpu_progression_hook_deregister(int hook_id);
 int starpu_idle_hook_register(unsigned (*func)(void *arg), void *arg);
 void starpu_idle_hook_deregister(int hook_id);
 
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif
 
-/** @} */
-
 #endif /* __STARPU_H__ */

include/starpu_fxt.h

@@ -21,11 +21,6 @@
 #ifndef __STARPU_FXT_H__
 #define __STARPU_FXT_H__
 
-/**
-   @defgroup API_FxT_Support FxT Support
-   @{
-*/
-
 #include <starpu_perfmodel.h>
 
 #ifdef __cplusplus
@@ -33,6 +28,11 @@ extern "C"
 {
 #endif
 
+/**
+   @defgroup API_FxT_Support FxT Support
+   @{
+*/
+
 #define STARPU_FXT_MAX_FILES	64
 
 struct starpu_fxt_codelet_event
@@ -145,10 +145,10 @@ void starpu_fxt_trace_user_event(unsigned long code);
 */
 void starpu_fxt_trace_user_event_string(const char *s);
 
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif
 
-/** @} */
-
 #endif /* __STARPU_FXT_H__ */

include/starpu_hash.h

@@ -19,11 +19,6 @@
 #ifndef __STARPU_HASH_H__
 #define __STARPU_HASH_H__
 
-/**
-   @ingroup API_Data_Interfaces
-   @{
-*/
-
 #include <stdint.h>
 #include <stddef.h>
 
@@ -33,6 +28,11 @@ extern "C"
 #endif
 
 /**
+   @ingroup API_Data_Interfaces
+   @{
+*/
+
+/**
    Compute the CRC of a byte buffer seeded by the \p inputcrc
    <em>current state</em>. The return value should be considered as the new
    <em>current state</em> for future CRC computation. This is used for computing
@@ -56,10 +56,10 @@ uint32_t starpu_hash_crc32c_be(uint32_t input, uint32_t inputcrc);
 */
 uint32_t starpu_hash_crc32c_string(const char *str, uint32_t inputcrc);
 
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif
 
-/** @} */
-
 #endif /* __STARPU_HASH_H__ */

include/starpu_mic.h

@@ -19,11 +19,6 @@
 #ifndef __STARPU_MIC_H__
 #define __STARPU_MIC_H__
 
-/**
-   @defgroup API_MIC_Extensions MIC Extensions
-   @{
-*/
-
 #include <starpu_config.h>
 
 #ifdef STARPU_USE_MIC
@@ -34,6 +29,11 @@ extern "C"
 #endif
 
 /**
+   @defgroup API_MIC_Extensions MIC Extensions
+   @{
+*/
+
+/**
    Type for MIC function symbols
 */
 typedef void *starpu_mic_func_symbol_t;
@@ -52,12 +52,12 @@ int starpu_mic_register_kernel(starpu_mic_func_symbol_t *symbol, const char *fun
 */
 starpu_mic_kernel_t starpu_mic_get_kernel(starpu_mic_func_symbol_t symbol);
 
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif
 
 #endif /* STARPU_USE_MIC */
 
-/** @} */
-
 #endif /* __STARPU_MIC_H__ */

include/starpu_mpi_ms.h

@@ -18,11 +18,6 @@
 #ifndef __STARPU_MPI_MS_H__
 #define __STARPU_MPI_MS_H__
 
-/**
-   @defgroup API_Master_Slave Master Slave Extension
-   @{
-*/
-
 #include <starpu_config.h>
 
 #ifdef STARPU_USE_MPI_MASTER_SLAVE
@@ -32,18 +27,23 @@ extern "C"
 {
 #endif
 
+/**
+   @defgroup API_Master_Slave Master Slave Extension
+   @{
+*/
+
 typedef void *starpu_mpi_ms_func_symbol_t;
 
 int starpu_mpi_ms_register_kernel(starpu_mpi_ms_func_symbol_t *symbol, const char *func_name);
 
 starpu_mpi_ms_kernel_t starpu_mpi_ms_get_kernel(starpu_mpi_ms_func_symbol_t symbol);
 
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif
 
 #endif /* STARPU_USE_MPI_MASTER_SLAVE */
 
-/** @} */
-
 #endif /* __STARPU_MPI_MS_H__ */

include/starpu_opencl.h

@@ -19,11 +19,6 @@
 #ifndef __STARPU_OPENCL_H__
 #define __STARPU_OPENCL_H__
 
-/**
-   @defgroup API_OpenCL_Extensions OpenCL Extensions
-   @{
-*/
-
 #include <starpu_config.h>
 #ifdef STARPU_USE_OPENCL
 #ifndef CL_TARGET_OPENCL_VERSION
@@ -42,6 +37,11 @@ extern "C"
 #endif
 
 /**
+   @defgroup API_OpenCL_Extensions OpenCL Extensions
+   @{
+*/
+
+/**
    Store the OpenCL programs as compiled for the different OpenCL
    devices.
 */
@@ -328,12 +328,12 @@ cl_int starpu_opencl_copy_async_sync(uintptr_t src, size_t src_offset, unsigned
 
 /** @} */
 
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif
 
 #endif /* STARPU_USE_OPENCL */
 
-/** @} */
-
 #endif /* __STARPU_OPENCL_H__ */

include/starpu_openmp.h

@@ -18,14 +18,14 @@
 #ifndef __STARPU_OPENMP_H__
 #define __STARPU_OPENMP_H__
 
+#include <starpu_config.h>
+
 /**
    @defgroup API_OpenMP_Runtime_Support OpenMP Runtime Support
    @brief This section describes the interface provided for implementing OpenMP runtimes on top of StarPU.
    @{
 */
 
-#include <starpu_config.h>
-
 #if defined STARPU_OPENMP
 /**
    Opaque Simple Lock object (\ref SimpleLock) for inter-task

include/starpu_perfmodel.h

@@ -21,11 +21,6 @@
 #ifndef __STARPU_PERFMODEL_H__
 #define __STARPU_PERFMODEL_H__
 
-/**
-   @defgroup API_Performance_Model Performance Model
-   @{
-*/
-
 #include <starpu.h>
 #include <stdio.h>
 
@@ -34,6 +29,11 @@ extern "C"
 {
 #endif
 
+/**
+   @defgroup API_Performance_Model Performance Model
+   @{
+*/
+
 struct starpu_task;
 struct starpu_data_descr;
 
@@ -432,10 +432,10 @@ double starpu_transfer_predict(unsigned src_node, unsigned dst_node, size_t size
 */
 extern struct starpu_perfmodel starpu_perfmodel_nop;
 
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif
 
-/** @} */
-
 #endif /* __STARPU_PERFMODEL_H__ */

include/starpu_profiling.h

@@ -19,11 +19,6 @@
 #ifndef __STARPU_PROFILING_H__
 #define __STARPU_PROFILING_H__
 
-/**
-   @defgroup API_Profiling Profiling
-   @{
-*/
-
 #include <starpu.h>
 #include <errno.h>
 #include <time.h>
@@ -34,6 +29,11 @@ extern "C"
 #endif
 
 /**
+   @defgroup API_Profiling Profiling
+   @{
+*/
+
+/**
    Used when calling the function starpu_profiling_status_set() to disable profiling.
 */
 #define STARPU_PROFILING_DISABLE	0
@@ -304,10 +304,10 @@ void starpu_profiling_worker_helper_display_summary(void);
 */
 void starpu_data_display_memory_stats();
 
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif
 
-/** @} */
-
 #endif /* __STARPU_PROFILING_H__ */

include/starpu_rand.h

@@ -19,11 +19,6 @@
 #ifndef __STARPU_RAND_H__
 #define __STARPU_RAND_H__
 
-/**
-   @defgroup API_Random_Functions Random Functions
-   @{
- */
-
 #include <stdlib.h>
 #include <starpu_config.h>
 
@@ -32,6 +27,11 @@ extern "C"
 {
 #endif
 
+/**
+   @defgroup API_Random_Functions Random Functions
+   @{
+ */
+
 #ifdef STARPU_SIMGRID
 /* In simgrid mode, force using seed 0 by default to get reproducible behavior by default */
 #define starpu_seed(seed)				starpu_get_env_number_default("STARPU_RAND_SEED", 0)
@@ -67,10 +67,10 @@ typedef int starpu_drand48_data;
 #  define starpu_erand48_r(xsubi, buffer, result)	do {(void) xsubi; (void) buffer; *(result) = ((double)(rand()) / RAND_MAX);} while (0)
 #endif
 
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif
 
-/** @} */
-
 #endif /* __STARPU_RAND_H__ */

include/starpu_scc.h

@@ -19,13 +19,13 @@
 #ifndef __STARPU_SCC_H__
 #define __STARPU_SCC_H__
 
+#include <starpu_config.h>
+
 /**
    @defgroup API_SCC_Extensions SCC Extensions
    @{
 */
 
-#include <starpu_config.h>
-
 #ifdef STARPU_USE_SCC
 
 /**

include/starpu_sched_component.h

@@ -21,11 +21,6 @@
 #ifndef __STARPU_SCHED_COMPONENT_H__
 #define __STARPU_SCHED_COMPONENT_H__
 
-/**
-   @defgroup API_Modularized_Scheduler Modularized Scheduler Interface
-   @{
-*/
-
 #include <starpu.h>
 
 #ifdef STARPU_HAVE_HWLOC
@@ -38,6 +33,11 @@ extern "C"
 #endif
 
 /**
+   @defgroup API_Modularized_Scheduler Modularized Scheduler Interface
+   @{
+*/
+
+/**
    flags for starpu_sched_component::properties
 */
 enum starpu_sched_component_properties
@@ -745,10 +745,10 @@ while(0)
 
 #define STARPU_COMPONENT_MUTEX_UNLOCK(m) STARPU_PTHREAD_MUTEX_UNLOCK((m))
 
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif
 
-/** @} */
-
 #endif /* __STARPU_SCHED_COMPONENT_H__ */

include/starpu_sched_ctx.h

@@ -21,11 +21,6 @@
 #ifndef __STARPU_SCHED_CTX_H__
 #define __STARPU_SCHED_CTX_H__
 
-/** @defgroup
- *
- * @{
- */
-
 #include <starpu.h>
 
 #ifdef __cplusplus
@@ -33,104 +28,268 @@ extern "C"
 {
 #endif
 
+/**
+   @defgroup API_Scheduling_Contexts Scheduling Contexts
+   @brief StarPU permits on one hand grouping workers in combined
+   workers in order to execute a parallel task and on the other hand
+   grouping tasks in bundles that will be executed by a single
+   specified worker.
+   In contrast when we group workers in scheduling contexts we submit
+   starpu tasks to them and we schedule them with the policy assigned
+   to the context. Scheduling contexts can be created, deleted and
+   modified dynamically.
+   @{
+*/
+
+/**
+   @name Scheduling Contexts Basic API
+   @{
+*/
+
+/**
+   Used when calling starpu_sched_ctx_create() to specify a
+   name for a scheduling policy
+*/
 #define STARPU_SCHED_CTX_POLICY_NAME		 (1<<16)
+
+/**
+   Used when calling starpu_sched_ctx_create() to specify a
+   pointer to a scheduling policy
+*/
 #define STARPU_SCHED_CTX_POLICY_STRUCT		 (2<<16)
+
+/**
+   Used when calling starpu_sched_ctx_create() to specify a
+   minimum scheduler priority value.
+*/
 #define STARPU_SCHED_CTX_POLICY_MIN_PRIO	 (3<<16)
+
+/**
+   Used when calling starpu_sched_ctx_create() to specify a
+   maximum scheduler priority value.
+*/
 #define STARPU_SCHED_CTX_POLICY_MAX_PRIO	 (4<<16)
+
 #define STARPU_SCHED_CTX_HIERARCHY_LEVEL         (5<<16)
 #define STARPU_SCHED_CTX_NESTED                  (6<<16)
+
+/**
+   Used when calling starpu_sched_ctx_create() to specify ???
+*/
 #define STARPU_SCHED_CTX_AWAKE_WORKERS           (7<<16)
+
+/**
+   Used when calling starpu_sched_ctx_create() to specify a
+   function pointer allowing to initialize the scheduling policy.
+*/
 #define STARPU_SCHED_CTX_POLICY_INIT             (8<<16)
+
+/**
+   Used when calling starpu_sched_ctx_create() to specify a
+   pointer to some user data related to the context being created.
+*/
 #define STARPU_SCHED_CTX_USER_DATA               (9<<16)
+
+/**
+   Used when calling starpu_sched_ctx_create() in order to create a
+   context on the NVIDIA GPU to specify the number of SMs the context
+   should have
+*/
 #define STARPU_SCHED_CTX_CUDA_NSMS               (10<<16)
+
+/**
+   Used when calling starpu_sched_ctx_create() to specify
+   a list of sub contexts of the current context.
+*/
 #define STARPU_SCHED_CTX_SUB_CTXS                (11<<16)
 
+/**
+   Create a scheduling context with the given parameters
+   (see below) and assign the workers in \p workerids_ctx to execute the
+   tasks submitted to it. The return value represents the identifier of
+   the context that has just been created. It will be further used to
+   indicate the context the tasks will be submitted to. The return value
+   should be at most ::STARPU_NMAX_SCHED_CTXS.
+
+   The arguments following the name of the scheduling context can be of
+   the following types:
+   <ul>
+   <li> ::STARPU_SCHED_CTX_POLICY_NAME, followed by the name of a
+   predefined scheduling policy. Use an empty string to create the
+   context with the default scheduling policy.
+   </li>
+   <li> ::STARPU_SCHED_CTX_POLICY_STRUCT, followed by a pointer to a
+   custom scheduling policy (struct starpu_sched_policy *)
+   </li>
+   <li> ::STARPU_SCHED_CTX_POLICY_MIN_PRIO, followed by a integer
+   representing the minimum priority value to be defined for the
+   scheduling policy.
+   </li>
+   <li> ::STARPU_SCHED_CTX_POLICY_MAX_PRIO, followed by a integer
+   representing the maximum priority value to be defined for the
+   scheduling policy.
+   </li>
+   <li> ::STARPU_SCHED_CTX_POLICY_INIT, followed by a function pointer
+   (ie. void init_sched(void)) allowing to initialize the scheduling policy.
+   </li>
+   <li> ::STARPU_SCHED_CTX_USER_DATA, followed by a pointer
+   to a custom user data structure, to be retrieved by \ref starpu_sched_ctx_get_user_data().
+   </li>
+   </ul>
+*/
 unsigned starpu_sched_ctx_create(int *workerids_ctx, int nworkers_ctx, const char *sched_ctx_name, ...);
 
+/**
+   Create a context indicating an approximate interval of resources
+*/
 unsigned starpu_sched_ctx_create_inside_interval(const char *policy_name, const char *sched_ctx_name, int min_ncpus, int max_ncpus, int min_ngpus, int max_ngpus, unsigned allow_overlap);
 
+/**
+   Execute the callback whenever the last task of the context finished
+   executing, it is called with the parameters \p sched_ctx and any
+   other parameter needed by the application (packed in \p args)
+*/
 void starpu_sched_ctx_register_close_callback(unsigned sched_ctx_id, void (*close_callback)(unsigned sched_ctx_id, void* args), void *args);
 
+/**
+   Add dynamically the workers in \p workerids_ctx to the context \p
+   sched_ctx_id. The last argument cannot be greater than
+   ::STARPU_NMAX_SCHED_CTXS.
+*/
 void starpu_sched_ctx_add_workers(int *workerids_ctx, unsigned nworkers_ctx, unsigned sched_ctx_id);
 
+/**
+   Remove the workers in \p workerids_ctx from the context
+   \p sched_ctx_id. The last argument cannot be greater than
+   ::STARPU_NMAX_SCHED_CTXS.
+*/
 void starpu_sched_ctx_remove_workers(int *workerids_ctx, unsigned nworkers_ctx, unsigned sched_ctx_id);
 
+/**
+   Print on the file \p f the worker names belonging to the context \p
+   sched_ctx_id
+*/
 void starpu_sched_ctx_display_workers(unsigned sched_ctx_id, FILE *f);
 
+/**
+   Delete scheduling context \p sched_ctx_id and transfer remaining
+   workers to the inheritor scheduling context.
+*/
 void starpu_sched_ctx_delete(unsigned sched_ctx_id);
 
+/**
+   Indicate that the context \p inheritor will inherit the resources
+   of the context \p sched_ctx_id when \p sched_ctx_id will be
+   deleted.
+*/
 void starpu_sched_ctx_set_inheritor(unsigned sched_ctx_id, unsigned inheritor);
 
 unsigned starpu_sched_ctx_get_inheritor(unsigned sched_ctx_id);
 
 unsigned starpu_sched_ctx_get_hierarchy_level(unsigned sched_ctx_id);
 
+/**
+   Set the scheduling context the subsequent tasks will be submitted
+   to
+*/
 void starpu_sched_ctx_set_context(unsigned *sched_ctx_id);
 
+/**
+   Return the scheduling context the tasks are currently submitted to,
+   or ::STARPU_NMAX_SCHED_CTXS if no default context has been defined
+   by calling the function starpu_sched_ctx_set_context().
+*/
 unsigned starpu_sched_ctx_get_context(void);
 
+/**
+   Stop submitting tasks from the empty context list until the next
+   time the context has time to check the empty context list
+*/
 void starpu_sched_ctx_stop_task_submission(void);
 
+/**
+   Indicate starpu that the application finished submitting to this
+   context in order to move the workers to the inheritor as soon as
+   possible.
+*/
 void starpu_sched_ctx_finished_submit(unsigned sched_ctx_id);
 
+/**
+   Return the list of workers in the array \p workerids, the return
+   value is the number of workers. The user should free the \p
+   workerids table after finishing using it (it is allocated inside
+   the function with the proper size)
+*/
 unsigned starpu_sched_ctx_get_workers_list(unsigned sched_ctx_id, int **workerids);
+
+/**
+   Return the list of workers in the array \p workerids, the return
+   value is the number of workers. This list is provided in raw order,
+   i.e. not sorted by tree or list order, and the user should not free
+   the \p workerids table. This function is thus much less costly than
+   starpu_sched_ctx_get_workers_list().
+*/
 unsigned starpu_sched_ctx_get_workers_list_raw(unsigned sched_ctx_id, int **workerids);
 
+/**
+   Return the number of workers managed by the specified context
+   (Usually needed to verify if it manages any workers or if it should
+   be blocked)
+*/
 unsigned starpu_sched_ctx_get_nworkers(unsigned sched_ctx_id);
 
+/**
+   Return the number of workers shared by two contexts.
+*/
 unsigned starpu_sched_ctx_get_nshared_workers(unsigned sched_ctx_id, unsigned sched_ctx_id2);
 
+/**
+   Return 1 if the worker belongs to the context and 0 otherwise
+*/
 unsigned starpu_sched_ctx_contains_worker(int workerid, unsigned sched_ctx_id);
 
 unsigned starpu_sched_ctx_contains_type_of_worker(enum starpu_worker_archtype arch, unsigned sched_ctx_id);
 
+/**
+   Return the workerid if the worker belongs to the context and -1 otherwise.
+   If the thread calling this function is not a worker the function returns -1
+   as it calls the function starpu_worker_get_id().
+*/
 unsigned starpu_sched_ctx_worker_get_id(unsigned sched_ctx_id);
 
 unsigned starpu_sched_ctx_get_ctx_for_task(struct starpu_task *task);
 
+/**
+   Check if a worker is shared between several contexts
+*/
 unsigned starpu_sched_ctx_overlapping_ctxs_on_worker(int workerid);
 
-int starpu_sched_get_min_priority(void);
-
-int starpu_sched_get_max_priority(void);
-
-int starpu_sched_set_min_priority(int min_prio);
-
-int starpu_sched_set_max_priority(int max_prio);
-
-int starpu_sched_ctx_get_min_priority(unsigned sched_ctx_id);
-
-int starpu_sched_ctx_get_max_priority(unsigned sched_ctx_id);
-
-int starpu_sched_ctx_set_min_priority(unsigned sched_ctx_id, int min_prio);
-
-int starpu_sched_ctx_set_max_priority(unsigned sched_ctx_id, int max_prio);
-
-int starpu_sched_ctx_min_priority_is_set(unsigned sched_ctx_id);
-
-int starpu_sched_ctx_max_priority_is_set(unsigned sched_ctx_id);
-
-#define STARPU_MIN_PRIO		(starpu_sched_get_min_priority())
-#define STARPU_MAX_PRIO		(starpu_sched_get_max_priority())
-
-#define STARPU_DEFAULT_PRIO	0
-
+/**
+   Return the user data pointer associated to the scheduling context.
+*/
 void *starpu_sched_ctx_get_user_data(unsigned sched_ctx_id);
 
 void starpu_sched_ctx_set_user_data(unsigned sched_ctx_id, void* user_data);
 
-struct starpu_worker_collection *starpu_sched_ctx_create_worker_collection(unsigned sched_ctx_id, enum starpu_worker_collection_type type) STARPU_ATTRIBUTE_MALLOC;
-
-void starpu_sched_ctx_delete_worker_collection(unsigned sched_ctx_id);
-
-struct starpu_worker_collection *starpu_sched_ctx_get_worker_collection(unsigned sched_ctx_id);
-
+/**
+   Allocate the scheduling policy data (private information of the
+   scheduler like queues, variables, additional condition variables)
+   the context
+*/
 void starpu_sched_ctx_set_policy_data(unsigned sched_ctx_id, void *policy_data);
 
+/**
+   Return the scheduling policy data (private information of the
+   scheduler) of the contexts previously assigned to.
+*/
 void *starpu_sched_ctx_get_policy_data(unsigned sched_ctx_id);
 
 struct starpu_sched_policy *starpu_sched_ctx_get_sched_policy(unsigned sched_ctx_id);
 
+/**
+   Execute any parallel code on the workers of the sched_ctx (workers
+   are blocked)
+*/
 void *starpu_sched_ctx_exec_parallel_code(void* (*func)(void*), void *param, unsigned sched_ctx_id);
 
 int starpu_sched_ctx_get_nready_tasks(unsigned sched_ctx_id);
@@ -161,11 +320,16 @@ int starpu_sched_ctx_book_workers_for_task(unsigned sched_ctx_id, int *workerids
 
 void starpu_sched_ctx_unbook_workers_for_task(unsigned sched_ctx_id, int master);
 
-/* return the first context (child of sched_ctx_id) where the workerid is master */
+/**
+   Return the first context (child of sched_ctx_id) where the workerid
+   is master
+ */
 unsigned starpu_sched_ctx_worker_is_master_for_child_ctx(int workerid, unsigned sched_ctx_id);
 
-/* Returns the context id of masterid if it master of a context. */
-/* If not, returns STARPU_NMAX_SCHED_CTXS. */
+/**
+   Return the context id of masterid if it master of a context. If
+   not, return ::STARPU_NMAX_SCHED_CTXS.
+*/
 unsigned starpu_sched_ctx_master_get_context(int masterid);
 
 void starpu_sched_ctx_revert_task_counters_ctx_locked(unsigned sched_ctx_id, double flops);
@@ -177,18 +341,100 @@ int starpu_sched_ctx_get_worker_rank(unsigned sched_ctx_id);
 void (*starpu_sched_ctx_get_sched_policy_init(unsigned sched_ctx_id))(unsigned);
 
 unsigned starpu_sched_ctx_has_starpu_scheduler(unsigned sched_ctx_id, unsigned *awake_workers);
-#ifdef STARPU_USE_SC_HYPERVISOR
-void starpu_sched_ctx_call_pushed_task_cb(int workerid, unsigned sched_ctx_id);
-#endif /* STARPU_USE_SC_HYPERVISOR */
 
 int starpu_sched_ctx_get_stream_worker(unsigned sub_ctx);
 int starpu_sched_ctx_get_nsms(unsigned sched_ctx);
 void starpu_sched_ctx_get_sms_interval(int stream_workerid, int *start, int *end);
 
+/** @} */
+
+/**
+   @name Scheduling Context Priorities
+   @{
+*/
+
+/**
+   Return the current minimum priority level supported by the
+   scheduling policy of the given scheduler context.
+*/
+int starpu_sched_ctx_get_min_priority(unsigned sched_ctx_id);
+
+/**
+   Return the current maximum priority level supported by the
+   scheduling policy of the given scheduler context.
+*/
+int starpu_sched_ctx_get_max_priority(unsigned sched_ctx_id);
+
+/**
+   Define the minimum task priority level supported by the scheduling
+   policy of the given scheduler context. The default minimum priority
+   level is the same as the default priority level which is 0 by
+   convention. The application may access that value by calling the
+   function starpu_sched_ctx_get_min_priority(). This function should
+   only be called from the initialization method of the scheduling
+   policy, and should not be used directly from the application.
+*/
+int starpu_sched_ctx_set_min_priority(unsigned sched_ctx_id, int min_prio);
+
+/**
+   Define the maximum priority level supported by the scheduling
+   policy of the given scheduler context. The default maximum priority
+   level is 1. The application may access that value by calling the
+   starpu_sched_ctx_get_max_priority() function. This function should
+   only be called from the initialization method of the scheduling
+   policy, and should not be used directly from the application.
+*/
+int starpu_sched_ctx_set_max_priority(unsigned sched_ctx_id, int max_prio);
+
+int starpu_sched_ctx_min_priority_is_set(unsigned sched_ctx_id);
+
+int starpu_sched_ctx_max_priority_is_set(unsigned sched_ctx_id);
+
+/**
+   Provided for legacy reasons.
+*/
+#define STARPU_MIN_PRIO		(starpu_sched_get_min_priority())
+
+/**
+   Provided for legacy reasons.
+*/
+#define STARPU_MAX_PRIO		(starpu_sched_get_max_priority())
+
+/**
+   By convention, the default priority level should be 0 so that we
+   can statically allocate tasks with a default priority.
+*/
+#define STARPU_DEFAULT_PRIO	0
+
+/** @} */
+
+/**
+   @name Scheduling Context Worker Collection
+   @{
+*/
+
+/**
+   Create a worker collection of the type indicated by the last
+   parameter for the context specified through the first parameter.
+*/
+struct starpu_worker_collection *starpu_sched_ctx_create_worker_collection(unsigned sched_ctx_id, enum starpu_worker_collection_type type) STARPU_ATTRIBUTE_MALLOC;
+
+/**
+   Delete the worker collection of the specified scheduling context
+*/
+void starpu_sched_ctx_delete_worker_collection(unsigned sched_ctx_id);
+
+/**
+   Return the worker collection managed by the indicated context
+*/
+struct starpu_worker_collection *starpu_sched_ctx_get_worker_collection(unsigned sched_ctx_id);
+
+/** @} */
+
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif
 
-/** @} */
-
 #endif /* __STARPU_SCHED_CTX_H__ */

include/starpu_sched_ctx_hypervisor.h

@@ -18,41 +18,93 @@
 #ifndef __STARPU_SCHED_CTX_HYPERVISOR_H__
 #define __STARPU_SCHED_CTX_HYPERVISOR_H__
 
-/** @defgroup
- *
- * @{
- */
-
 #ifdef __cplusplus
 extern "C"
 {
 #endif
 
+/**
+   @ingroup API_Scheduling_Contexts
+   @{
+*/
+
+/**
+   @name Scheduling Context Link with Hypervisor
+   @{
+*/
+
+/**
+   Performance counters used by the starpu to indicate the hypervisor
+   how the application and the resources are executing.
+ */
 struct starpu_sched_ctx_performance_counters
 {
+	/**
+	   Inform the hypervisor for how long a worker has been idle
+	   in the specified context
+	*/
 	void (*notify_idle_cycle)(unsigned sched_ctx_id, int worker, double idle_time);
+
+	/**
+	   Inform the hypervisor that a task executing a specified
+	   number of instructions has been poped from the worker
+	*/
 	void (*notify_poped_task)(unsigned sched_ctx_id, int worker);
+
+	/**
+	   Notify the hypervisor that a task has been scheduled on
+	   the queue of the worker corresponding to the specified
+	   context
+	*/
 	void (*notify_pushed_task)(unsigned sched_ctx_id, int worker);
+
+	/**
+	   Notify the hypervisor that a task has just been executed
+	*/
 	void (*notify_post_exec_task)(struct starpu_task *task, size_t data_size, uint32_t footprint, int hypervisor_tag, double flops);
+
+	/**
+	   Notify the hypervisor that a task has just been submitted
+	*/
 	void (*notify_submitted_job)(struct starpu_task *task, uint32_t footprint, size_t data_size);
+
 	void (*notify_empty_ctx)(unsigned sched_ctx_id, struct starpu_task *task);
+
+	/**
+	   Notify the hypervisor that the context was deleted
+	*/
 	void (*notify_delete_context)(unsigned sched_ctx);
 };
 
-#ifdef STARPU_USE_SC_HYPERVISOR
+/**
+   Indicate to starpu the pointer to the performance counter
+*/
 void starpu_sched_ctx_set_perf_counters(unsigned sched_ctx_id, void *perf_counters);
-#endif //STARPU_USE_SC_HYPERVISOR
 
+/**
+   Callback that lets the scheduling policy tell the hypervisor that a
+   task was pushed on a worker
+*/
+void starpu_sched_ctx_call_pushed_task_cb(int workerid, unsigned sched_ctx_id);
+
+/**
+   Allow the hypervisor to let starpu know it's initialised
+*/
 void starpu_sched_ctx_notify_hypervisor_exists(void);
 
+/**
+   Ask starpu if it is informed if the hypervisor is initialised
+*/
 unsigned starpu_sched_ctx_check_if_hypervisor_exists(void);
 
 void starpu_sched_ctx_update_start_resizing_sample(unsigned sched_ctx_id, double start_sample);
 
+/** @} */
+
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif
 
-/** @} */
-
 #endif /* __STARPU_SCHED_CTX_HYPERVISOR_H__ */

include/starpu_scheduler.h

@@ -2,7 +2,7 @@
  *
  * Copyright (C) 2011-2013,2015-2017                      Inria
  * Copyright (C) 2010-2018                                Université de Bordeaux
- * Copyright (C) 2011-2013,2015,2017,2019                      CNRS
+ * Copyright (C) 2011-2013,2015,2017,2019                 CNRS
  * Copyright (C) 2013                                     Thibaut Lambert
  * Copyright (C) 2011                                     Télécom-SudParis
  * Copyright (C) 2016                                     Uppsala University
@@ -22,11 +22,6 @@
 #ifndef __STARPU_SCHEDULER_H__
 #define __STARPU_SCHEDULER_H__
 
-/** @defgroup
- *
- * @{
- */
-
 #include <starpu.h>
 
 #ifdef __cplusplus
@@ -34,92 +29,418 @@ extern "C"
 {
 #endif
 
+/**
+   @defgroup API_Scheduling_Policy Scheduling Policy
+   @brief TODO. While StarPU comes with a variety of scheduling
+   policies (see \ref TaskSchedulingPolicy), it may sometimes be
+   desirable to implement custom policies to address specific
+   problems. The API described below allows users to write their own
+   scheduling policy.
+   @{
+*/
+
 struct starpu_task;
 
+/**
+   Contain all the methods that implement a scheduling policy. An
+   application may specify which scheduling strategy in the field
+   starpu_conf::sched_policy passed to the function starpu_init().
+
+   For each task going through the scheduler, the following methods
+   get called in the given order:
+
+   <ul>
+   <li>starpu_sched_policy::submit_hook when the task is
+   submitted</li>
+   <li>starpu_sched_policy::push_task when the task becomes ready. The
+   scheduler is here <b>given</b> the task</li>
+   <li>starpu_sched_policy::pop_task when the worker is idle. The
+   scheduler here <b>gives</b> back the task to the core. It must not
+   access this task any more</li>
+   <li>starpu_sched_policy::pre_exec_hook right before the worker
+   actually starts the task computation (after transferring any
+   missing data).</li>
+   <li>starpu_sched_policy::post_exec_hook right after the worker
+   actually completes the task computation.</li>
+   </ul>
+
+   For each task not going through the scheduler (because
+   starpu_task::execute_on_a_specific_worker was set), these get
+   called:
+
+   <ul>
+   <li>starpu_sched_policy::submit_hook when the task is
+   submitted</li>
+   <li>starpu_sched_policy::push_task_notify when the task becomes
+   ready. This is just a notification, the scheduler does not have to
+   do anything about the task.</li>
+   <li>starpu_sched_policy::pre_exec_hook right before the worker
+   actually starts the task computation (after transferring any
+   missing data).</li>
+   <li>starpu_sched_policy::post_exec_hook right after the worker
+   actually completes the task computation.</li>
+   </ul>
+*/
 struct starpu_sched_policy
 {
+	/**
+	   Initialize the scheduling policy, called before any other
+	   method.
+	*/
 	void (*init_sched)(unsigned sched_ctx_id);
+	/**
+	   Cleanup the scheduling policy
+	*/
 	void (*deinit_sched)(unsigned sched_ctx_id);
 
+	/**
+	   Insert a task into the scheduler, called when the task
+	   becomes ready for execution. This must call
+	   starpu_push_task_end() once it has effectively pushed the
+	   task to a queue (to note the time when this was done in the
+	   task), but before releasing mutexes (so that the task
+	   hasn't been already taken by a worker).
+	*/
 	int (*push_task)(struct starpu_task *);
+
 	double (*simulate_push_task)(struct starpu_task *);
+
+	/**
+	   Notify the scheduler that a task was pushed on a given
+	   worker. This method is called when a task that was
+	   explicitly assigned to a worker becomes ready and is about
+	   to be executed by the worker. This method therefore permits
+	   to keep the state of the scheduler coherent even when
+	   StarPU bypasses the scheduling strategy.
+	*/
 	void (*push_task_notify)(struct starpu_task *, int workerid, int perf_workerid, unsigned sched_ctx_id);
+
+	/**
+	   Get a task from the scheduler.
+	   If this method returns NULL, the worker will start
+	   sleeping. If later on some task are pushed for this worker,
+	   starpu_wake_worker() must be called to wake the worker so
+	   it can call the pop_task() method again.
+	   The mutex associated to the worker is already taken when
+	   this method is called. This method may release it (e.g. for
+	   scalability reasons when doing work stealing), but it must
+	   acquire it again before taking the decision whether to
+	   return a task or NULL, so the atomicity of deciding to
+	   return NULL and making the worker actually sleep is
+	   preserved. Otherwise in simgrid or blocking driver mode the
+	   worker might start sleeping while a task has just been
+	   pushed for it.
+	   If this method is defined as <c>NULL</c>, the worker will
+	   only execute tasks from its local queue. In this case, the
+	   push_task method should use the starpu_push_local_task
+	   method to assign tasks to the different workers.
+	*/
 	struct starpu_task *(*pop_task)(unsigned sched_ctx_id);
+
+	/**
+	   Remove all available tasks from the scheduler (tasks are
+	   chained by the means of the field starpu_task::prev and
+	   starpu_task::next). The mutex associated to the worker is
+	   already taken when this method is called. This is currently
+	   not used and can be discarded.
+	*/
 	struct starpu_task *(*pop_every_task)(unsigned sched_ctx_id);
 
+	/**
+	   Optional field. This method is called when a task is
+	   submitted.
+	*/
 	void (*submit_hook)(struct starpu_task *task);
+
+	/**
+	   Optional field. This method is called every time a task is
+	   starting.
+	*/
 	void (*pre_exec_hook)(struct starpu_task *, unsigned sched_ctx_id);
+
+	/**
+	   Optional field. This method is called every time a task has
+	   been executed.
+	*/
 	void (*post_exec_hook)(struct starpu_task *, unsigned sched_ctx_id);
 
+	/**
+	   Optional field. This method is called when it is a good
+	   time to start scheduling tasks. This is notably called when
+	   the application calls starpu_task_wait_for_all() or
+	   starpu_do_schedule() explicitly.
+	*/
 	void (*do_schedule)(unsigned sched_ctx_id);
 
+	/**
+	   Initialize scheduling structures corresponding to each
+	   worker used by the policy.
+	*/
 	void (*add_workers)(unsigned sched_ctx_id, int *workerids, unsigned nworkers);
+
+	/**
+	   Deinitialize scheduling structures corresponding to each
+	   worker used by the policy.
+	*/
 	void (*remove_workers)(unsigned sched_ctx_id, int *workerids, unsigned nworkers);
 
+	/**
+	   Optional field. Name of the policy.
+	*/
 	const char *policy_name;
+
+	/**
+	   Optional field. Human readable description of the policy.
+	*/
 	const char *policy_description;
 
 	enum starpu_worker_collection_type worker_type;
 };
 
+/**
+   Return an <c>NULL</c>-terminated array of all the predefined
+   scheduling policies.
+*/
 struct starpu_sched_policy **starpu_sched_get_predefined_policies();
 
+/**
+   When there is no available task for a worker, StarPU blocks this
+   worker on a condition variable. This function specifies which
+   condition variable (and the associated mutex) should be used to
+   block (and to wake up) a worker. Note that multiple workers may use
+   the same condition variable. For instance, in the case of a
+   scheduling strategy with a single task queue, the same condition
+   variable would be used to block and wake up all workers.
+*/
 void starpu_worker_get_sched_condition(int workerid, starpu_pthread_mutex_t **sched_mutex, starpu_pthread_cond_t **sched_cond);
 unsigned long starpu_task_get_job_id(struct starpu_task *task);
 
+/**
+   Must be called to wake up a worker that is sleeping on the cond.
+   Return 0 whenever the worker is not in a sleeping state or has the
+   state_keep_awake flag on.
+*/
 int starpu_wake_worker_no_relax(int workerid);
+
+/**
+   Version of starpu_wake_worker_no_relax() which assumes that the
+   sched mutex is locked
+*/
 int starpu_wake_worker_locked(int workerid);
+
 int starpu_wake_worker_relax_light(int workerid);
 
+/**
+   TODO: check if this is correct
+   Return the current minimum priority level supported by the scheduling
+   policy
+*/
+int starpu_sched_get_min_priority(void);
+
+/**
+   TODO: check if this is correct
+   Return the current maximum priority level supported by the
+   scheduling policy
+*/
+int starpu_sched_get_max_priority(void);
+
+/**
+   TODO: check if this is correct
+   Define the minimum task priority level supported by the scheduling
+   policy. The default minimum priority level is the same as the
+   default priority level which is 0 by convention. The application
+   may access that value by calling the function
+   starpu_sched_get_min_priority(). This function should only be
+   called from the initialization method of the scheduling policy, and
+   should not be used directly from the application.
+*/
+int starpu_sched_set_min_priority(int min_prio);
+
+/**
+   TODO: check if this is correct
+   Define the maximum priority level supported by the scheduling
+   policy. The default maximum priority level is 1. The application
+   may access that value by calling the function
+   starpu_sched_get_max_priority(). This function should only be
+   called from the initialization method of the scheduling policy, and
+   should not be used directly from the application.
+*/
+int starpu_sched_set_max_priority(int max_prio);
+
+/**
+   Check if the worker specified by workerid can execute the codelet.
+   Schedulers need to call it before assigning a task to a worker,
+   otherwise the task may fail to execute.
+*/
 int starpu_worker_can_execute_task(unsigned workerid, struct starpu_task *task, unsigned nimpl);
+
+/**
+   Check if the worker specified by workerid can execute the codelet
+   and return which implementation numbers can be used.
+   Schedulers need to call it before assigning a task to a worker,
+   otherwise the task may fail to execute.
+   This should be preferred rather than calling
+   starpu_worker_can_execute_task() for each and every implementation.
+   It can also be used with <c>impl_mask == NULL</c> to check for at
+   least one implementation without determining which.
+*/
 int starpu_worker_can_execute_task_impl(unsigned workerid, struct starpu_task *task, unsigned *impl_mask);
+
+/**
+   Check if the worker specified by workerid can execute the codelet
+   and return the first implementation which can be used.
+   Schedulers need to call it before assigning a task to a worker,
+   otherwise the task may fail to execute. This should be preferred
+   rather than calling starpu_worker_can_execute_task() for
+   each and every implementation. It can also be used with
+   <c>impl_mask == NULL</c> to check for at least one implementation
+   without determining which.
+*/
 int starpu_worker_can_execute_task_first_impl(unsigned workerid, struct starpu_task *task, unsigned *nimpl);
 
+/**
+   The scheduling policy may put tasks directly into a worker’s local
+   queue so that it is not always necessary to create its own queue
+   when the local queue is sufficient. If \p back is not 0, \p task is
+   put at the back of the queue where the worker will pop tasks first.
+   Setting \p back to 0 therefore ensures a FIFO ordering.
+*/
 int starpu_push_local_task(int workerid, struct starpu_task *task, int back);
 
+/**
+   Must be called by a scheduler to notify that the given
+   task has just been pushed.
+*/
 int starpu_push_task_end(struct starpu_task *task);
 
 int starpu_combined_worker_assign_workerid(int nworkers, int workerid_array[]);
 int starpu_combined_worker_get_description(int workerid, int *worker_size, int **combined_workerid);
 int starpu_combined_worker_can_execute_task(unsigned workerid, struct starpu_task *task, unsigned nimpl);
 
+/**
+   Whether \ref STARPU_PREFETCH was set
+*/
 int starpu_get_prefetch_flag(void);
+
+/**
+   Prefetch data for a given p task on a given p node with a given
+   priority
+*/
 int starpu_prefetch_task_input_on_node_prio(struct starpu_task *task, unsigned node, int prio);
+
+/**
+   Prefetch data for a given p task on a given p node
+*/
 int starpu_prefetch_task_input_on_node(struct starpu_task *task, unsigned node);
+
+/**
+   Prefetch data for a given p task on a given p node when the bus is
+   idle with a given priority
+*/
 int starpu_idle_prefetch_task_input_on_node_prio(struct starpu_task *task, unsigned node, int prio);
+
+/**
+   Prefetch data for a given p task on a given p node when the bus is
+   idle
+*/
 int starpu_idle_prefetch_task_input_on_node(struct starpu_task *task, unsigned node);
 
+/**
+   Prefetch data for a given p task on a given p worker with a given
+   priority
+*/
 int starpu_prefetch_task_input_for_prio(struct starpu_task *task, unsigned worker, int prio);
+
+/**
+   Prefetch data for a given p task on a given p worker
+*/
 int starpu_prefetch_task_input_for(struct starpu_task *task, unsigned worker);
+
+/**
+   Prefetch data for a given p task on a given p worker when the bus
+   is idle with a given priority
+*/
 int starpu_idle_prefetch_task_input_for_prio(struct starpu_task *task, unsigned worker, int prio);
+
+/**
+   Prefetch data for a given p task on a given p worker when the bus
+   is idle
+*/
 int starpu_idle_prefetch_task_input_for(struct starpu_task *task, unsigned worker);
 
+/**
+   Return the footprint for a given task, taking into account
+   user-provided perfmodel footprint or size_base functions.
+*/
 uint32_t starpu_task_footprint(struct starpu_perfmodel *model, struct starpu_task *task, struct starpu_perfmodel_arch *arch, unsigned nimpl);
+
+/**
+   Return the raw footprint for the data of a given task (without
+   taking into account user-provided functions).
+*/
 uint32_t starpu_task_data_footprint(struct starpu_task *task);
+
+/**
+   Return expected task duration in micro-seconds.
+*/
 double starpu_task_expected_length(struct starpu_task *task, struct starpu_perfmodel_arch *arch, unsigned nimpl);
+
+/**
+   Return an estimated speedup factor relative to CPU speed
+*/
 double starpu_worker_get_relative_speedup(struct starpu_perfmodel_arch *perf_arch);
+
+/**
+   Return expected data transfer time in micro-seconds for the given \p
+   memory_node. Prefer using starpu_task_expected_data_transfer_time_for() which is
+   more precise.
+*/
 double starpu_task_expected_data_transfer_time(unsigned memory_node, struct starpu_task *task);
+
+/**
+   Return expected data transfer time in micro-seconds for the given
+   \p worker.
+*/
 double starpu_task_expected_data_transfer_time_for(struct starpu_task *task, unsigned worker);
+
+/**
+   Predict the transfer time (in micro-seconds) to move \p handle to a
+   memory node
+*/
 double starpu_data_expected_transfer_time(starpu_data_handle_t handle, unsigned memory_node, enum starpu_data_access_mode mode);
+
+/**
+   Return expected energy consumption in J
+*/
 double starpu_task_expected_energy(struct starpu_task *task, struct starpu_perfmodel_arch *arch, unsigned nimpl);
-double starpu_task_expected_conversion_time(struct starpu_task *task, struct starpu_perfmodel_arch *arch, unsigned nimpl);
 
-double starpu_task_bundle_expected_length(starpu_task_bundle_t bundle, struct starpu_perfmodel_arch *arch, unsigned nimpl);
-double starpu_task_bundle_expected_data_transfer_time(starpu_task_bundle_t bundle, unsigned memory_node);
-double starpu_task_bundle_expected_energy(starpu_task_bundle_t bundle, struct starpu_perfmodel_arch *arch, unsigned nimpl);
+/**
+   Return expected conversion time in ms (multiformat interface only)
+*/
+double starpu_task_expected_conversion_time(struct starpu_task *task, struct starpu_perfmodel_arch *arch, unsigned nimpl);
 
 typedef void (*starpu_notify_ready_soon_func)(void *data, struct starpu_task *task, double delay);
-void starpu_task_notify_ready_soon_register(starpu_notify_ready_soon_func f, void *data);
 
+/**
+   Register a callback to be called when it is determined when a task
+   will be ready an estimated amount of time from now, because its
+   last dependency has just started and we know how long it will take.
+*/
+void starpu_task_notify_ready_soon_register(starpu_notify_ready_soon_func f, void *data);
 
+/**
+   The scheduling policies indicates if the worker may pop tasks from
+   the list of other workers or if there is a central list with task
+   for all the workers
+*/
 void starpu_sched_ctx_worker_shares_tasks_lists(int workerid, int sched_ctx_id);
 
 void starpu_sched_task_break(struct starpu_task *task);
 
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif
 
-/** @} */
-
 #endif /* __STARPU_SCHEDULER_H__ */

include/starpu_sink.h

@@ -19,10 +19,10 @@
 #ifndef __STARPU_SINK_H__
 #define __STARPU_SINK_H__
 
-/** @defgroup
- *
- * @{
- */
+/**
+   @defgroup API_Sink Sink
+   @{
+*/
 
 void starpu_sink_common_worker(int argc, char **argv);
 

include/starpu_stdlib.h

@@ -19,11 +19,6 @@
 #ifndef __STARPU_STDLIB_H__
 #define __STARPU_STDLIB_H__
 
-/** @defgroup
- *
- * @{
- */
-
 #include <starpu.h>
 
 #ifdef __cplusplus
@@ -31,58 +26,227 @@ extern "C"
 {
 #endif
 
+/**
+   @defgroup API_Standard_Memory_Library Standard Memory Library
+   @{
+*/
+
+/**
+   Value passed to the function starpu_malloc_flags() to indicate the
+   memory allocation should be pinned.
+*/
 #define STARPU_MALLOC_PINNED	((1ULL)<<1)
+
+/**
+   Value passed to the function starpu_malloc_flags() to indicate the
+   memory allocation should be in the limit defined by the environment
+   variables \ref STARPU_LIMIT_CUDA_devid_MEM, \ref
+   STARPU_LIMIT_CUDA_MEM, \ref STARPU_LIMIT_OPENCL_devid_MEM, \ref
+   STARPU_LIMIT_OPENCL_MEM and \ref STARPU_LIMIT_CPU_MEM (see Section
+   \ref HowToLimitMemoryPerNode).
+   If no memory is available, it tries to reclaim memory from StarPU.
+   Memory allocated this way needs to be freed by calling the function
+   starpu_free_flags() with the same flag.
+*/
 #define STARPU_MALLOC_COUNT	((1ULL)<<2)
+
+/**
+   Value passed to the function starpu_malloc_flags() along
+   ::STARPU_MALLOC_COUNT to indicate that while the memory allocation
+   should be kept in the limits defined for ::STARPU_MALLOC_COUNT, no
+   reclaiming should be performed by starpu_malloc_flags() itself,
+   thus potentially overflowing the memory node a bit. StarPU will
+   reclaim memory after next task termination, according to the \ref
+   STARPU_MINIMUM_AVAILABLE_MEM, \ref STARPU_TARGET_AVAILABLE_MEM,
+   \ref STARPU_MINIMUM_CLEAN_BUFFERS, and \ref
+   STARPU_TARGET_CLEAN_BUFFERS environment variables. If
+   ::STARPU_MEMORY_WAIT is set, no overflowing will happen,
+   starpu_malloc_flags() will wait for other eviction mechanisms to
+   release enough memory.
+*/
 #define STARPU_MALLOC_NORECLAIM	((1ULL)<<3)
 
+/**
+   Value passed to starpu_memory_allocate() to specify that the
+   function should wait for the requested amount of memory to become
+   available, and atomically allocate it.
+*/
 #define STARPU_MEMORY_WAIT	((1ULL)<<4)
+
+/**
+   Value passed to starpu_memory_allocate() to specify that the
+   function should allocate the amount of memory, even if that means
+   overflowing the total size of the memory node.
+*/
 #define STARPU_MEMORY_OVERFLOW	((1ULL)<<5)
 
+/**
+   Value passed to the function starpu_malloc_flags() to indicate that
+   when StarPU is using simgrid, the allocation can be "folded", i.e.
+   a memory area is allocated, but its content is actually a replicate
+   of the same memory area, to avoid having to actually allocate that
+   much memory . This thus allows to have a memory area that does not
+   actually consumes memory, to which one can read from and write to
+   normally, but get bogus values.
+*/
 #define STARPU_MALLOC_SIMULATION_FOLDED	((1ULL)<<6)
 
 /**
-   \deprecated
+   @deprecated
    Equivalent to starpu_malloc(). This macro is provided to avoid
    breaking old codes.
 */
 #define starpu_data_malloc_pinned_if_possible	starpu_malloc
+
+/**
+   @deprecated
+   Equivalent to starpu_free(). This macro is provided to avoid
+   breaking old codes.
+*/
 #define starpu_data_free_pinned_if_possible	starpu_free
 
+/**
+   Set an alignment constraints for starpu_malloc() allocations. \p
+   align must be a power of two. This is for instance called
+   automatically by the OpenCL driver to specify its own alignment
+   constraints.
+*/
 void starpu_malloc_set_align(size_t align);
 
+/**
+   Allocate data of the given size \p dim in main memory, and return
+   the pointer to the allocated data through \p A. It will also try to
+   pin it in CUDA or OpenCL, so that data transfers from this buffer
+   can be asynchronous, and thus permit data transfer and computation
+   overlapping. The allocated buffer must be freed thanks to the
+   starpu_free() function.
+*/
 int starpu_malloc(void **A, size_t dim);
+
+/**
+   Free memory which has previously been allocated with
+   starpu_malloc().
+*/
 int starpu_free(void *A);
 
+/**
+   Perform a memory allocation based on the constraints defined by the
+   given flag.
+*/
 int starpu_malloc_flags(void **A, size_t dim, int flags);
+
+/**
+   Free memory by specifying its size. The given flags should be
+   consistent with the ones given to starpu_malloc_flags() when
+   allocating the memory.
+*/
 int starpu_free_flags(void *A, size_t dim, int flags);
 
 typedef int (*starpu_malloc_hook)(unsigned dst_node, void **A, size_t dim, int flags);
 typedef int (*starpu_free_hook)(unsigned dst_node, void *A, size_t dim, int flags);
 
+/**
+   Set allocation functions to be used by StarPU. By default, StarPU
+   will use \c malloc() (or \c cudaHostAlloc() if CUDA GPUs are used)
+   for all its data handle allocations. The application can specify
+   another allocation primitive by calling this. The malloc_hook
+   should pass the allocated pointer through the \c A parameter, and
+   return 0 on success. On allocation failure, it should return
+   -ENOMEM. The \c flags parameter contains ::STARPU_MALLOC_PINNED if
+   the memory should be pinned by the hook for GPU transfer
+   efficiency. The hook can use starpu_memory_pin() to achieve this.
+   The \c dst_node parameter is the starpu memory node, one can
+   convert it to an hwloc logical id with
+   starpu_memory_nodes_numa_id_to_hwloclogid() or to an OS NUMA number
+   with starpu_memory_nodes_numa_devid_to_id().
+*/
 void starpu_malloc_set_hooks(starpu_malloc_hook malloc_hook, starpu_free_hook free_hook);
 
+/**
+   Pin the given memory area, so that CPU-GPU transfers can be done
+   asynchronously with DMAs. The memory must be unpinned with
+   starpu_memory_unpin() before being freed. Return 0 on success, -1
+   on error.
+*/
 int starpu_memory_pin(void *addr, size_t size);
+
+/**
+   Unpin the given memory area previously pinned with
+   starpu_memory_pin(). Return 0 on success, -1 on error.
+*/
 int starpu_memory_unpin(void *addr, size_t size);
 
+/**
+   If a memory limit is defined on the given node (see Section \ref
+   HowToLimitMemoryPerNode), return the amount of total memory on the
+   node. Otherwise return -1.
+*/
 starpu_ssize_t starpu_memory_get_total(unsigned node);
+
+/**
+   If a memory limit is defined on the given node (see Section \ref
+   HowToLimitMemoryPerNode), return the amount of available memory on
+   the node. Otherwise return -1.
+*/
 starpu_ssize_t starpu_memory_get_available(unsigned node);
+
+/**
+   Return the amount of total memory on all memory nodes for whose a
+   memory limit is defined (see Section \ref HowToLimitMemoryPerNode).
+*/
 starpu_ssize_t starpu_memory_get_total_all_nodes();
-starpu_ssize_t starpu_memory_get_available_all_nodes();
 
-void starpu_memory_wait_available(unsigned node, size_t size);
+/**
+   Return the amount of available memory on all memory nodes for whose
+   a memory limit is defined (see Section \ref
+   HowToLimitMemoryPerNode).
+*/
+starpu_ssize_t starpu_memory_get_available_all_nodes();
 
-/* Try to allocate memory on the given node */
+/**
+   If a memory limit is defined on the given node (see Section \ref
+   HowToLimitMemoryPerNode), try to allocate some of it. This does not
+   actually allocate memory, but only accounts for it. This can be
+   useful when the application allocates data another way, but want
+   StarPU to be aware of the allocation size e.g. for memory
+   reclaiming.
+   By default, return <c>-ENOMEM</c> if there is not enough room on
+   the given node. \p flags can be either ::STARPU_MEMORY_WAIT or
+   ::STARPU_MEMORY_OVERFLOW to change this.
+*/
 int starpu_memory_allocate(unsigned node, size_t size, int flags);
 
-/* Indicates the given amount of memory is going to be deallocated from the given node */
+/**
+   If a memory limit is defined on the given node (see Section \ref
+   HowToLimitMemoryPerNode), free some of it. This does not actually
+   free memory, but only accounts for it, like
+   starpu_memory_allocate(). The amount does not have to be exactly
+   the same as what was passed to starpu_memory_allocate(), only the
+   eventual amount needs to be the same, i.e. one call to
+   starpu_memory_allocate() can be followed by several calls to
+   starpu_memory_deallocate() to declare the deallocation piece by
+   piece.
+*/
 void starpu_memory_deallocate(unsigned node, size_t size);
 
+/**
+   If a memory limit is defined on the given node (see Section \ref
+   HowToLimitMemoryPerNode), this will wait for \p size bytes to
+   become available on \p node. Of course, since another thread may be
+   allocating memory concurrently, this does not necessarily mean that
+   this amount will be actually available, just that it was reached.
+   To atomically wait for some amount of memory and reserve it,
+   starpu_memory_allocate() should be used with the
+   ::STARPU_MEMORY_WAIT flag.
+*/
+void starpu_memory_wait_available(unsigned node, size_t size);
+
 void starpu_sleep(float nb_sec);
 
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif
 
-/** @} */
-
 #endif /* __STARPU_STDLIB_H__ */

include/starpu_task_bundle.h

@@ -2,7 +2,7 @@
  *
  * Copyright (C) 2010,2011,2014                           Université de Bordeaux
  * Copyright (C) 2011,2012                                Inria
- * Copyright (C) 2011-2013,2015,2017,2019                      CNRS
+ * Copyright (C) 2011-2013,2015,2017,2019                 CNRS
  * Copyright (C) 2011                                     Télécom-SudParis
  *
  * StarPU is free software; you can redistribute it and/or modify
@@ -20,32 +20,80 @@
 #ifndef __STARPU_TASK_BUNDLE_H__
 #define __STARPU_TASK_BUNDLE_H__
 
-/** @defgroup
- *
- * @{
- */
-
 #ifdef __cplusplus
 extern "C"
 {
 #endif
 
+/**
+   @defgroup API_Task_Bundles Task Bundles
+   @{
+*/
+
 struct starpu_task;
+struct starpu_perfmodel_arch;
 
+/**
+   Opaque structure describing a list of tasks that should be
+   scheduled on the same worker whenever it’s possible. It must be
+   considered as a hint given to the scheduler as there is no
+   guarantee that they will be executed on the same worker.
+*/
 typedef struct _starpu_task_bundle *starpu_task_bundle_t;
 
+/**
+   Factory function creating and initializing \p bundle, when the call
+   returns, memory needed is allocated and \p bundle is ready to use.
+*/
 void starpu_task_bundle_create(starpu_task_bundle_t *bundle);
 
+/**
+   Insert \p task in \p bundle. Until \p task is removed from \p
+   bundle its expected length and data transfer time will be
+   considered along those of the other tasks of bundle. This function
+   must not be called if \p bundle is already closed and/or \p task is
+   already submitted. On success, it returns 0. There are two cases of
+   error : if \p bundle is already closed it returns <c>-EPERM</c>, if
+   \p task was already submitted it returns <c>-EINVAL</c>.
+*/
 int starpu_task_bundle_insert(starpu_task_bundle_t bundle, struct starpu_task *task);
 
+/**
+   Remove \p task from \p bundle. Of course \p task must have been
+   previously inserted in \p bundle. This function must not be called
+   if \p bundle is already closed and/or \p task is already submitted.
+   Doing so would result in undefined behaviour. On success, it
+   returns 0. If \p bundle is already closed it returns
+   <c>-ENOENT</c>.
+*/
 int starpu_task_bundle_remove(starpu_task_bundle_t bundle, struct starpu_task *task);
 
+/**
+   Inform the runtime that the user will not modify \p bundle anymore,
+   it means no more inserting or removing task. Thus the runtime can
+   destroy it when possible.
+*/
 void starpu_task_bundle_close(starpu_task_bundle_t bundle);
 
+/**
+   Return the expected duration of \p bundle in micro-seconds.
+*/
+double starpu_task_bundle_expected_length(starpu_task_bundle_t bundle, struct starpu_perfmodel_arch *arch, unsigned nimpl);
+
+/**
+   Return the time (in micro-seconds) expected to transfer all data used within \p bundle.
+*/
+double starpu_task_bundle_expected_data_transfer_time(starpu_task_bundle_t bundle, unsigned memory_node);
+
+/**
+   Return the expected energy consumption of \p bundle in J.
+*/
+double starpu_task_bundle_expected_energy(starpu_task_bundle_t bundle, struct starpu_perfmodel_arch *arch, unsigned nimpl);
+
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif
 
-/** @} */
-
 #endif /* __STARPU_TASK_BUNDLE_H__ */

include/starpu_task_dep.h

@@ -0,0 +1,223 @@
+/* StarPU --- Runtime system for heterogeneous multicore architectures.
+ *
+ * Copyright (C) 2011-2017                                Inria
+ * Copyright (C) 2009-2018                                Université de Bordeaux
+ * Copyright (C) 2010-2015,2017,2018,2019                 CNRS
+ * Copyright (C) 2011                                     Télécom-SudParis
+ * Copyright (C) 2016                                     Uppsala University
+ *
+ * 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.
+ */
+
+#ifndef __STARPU_TASK_DEP_H__
+#define __STARPU_TASK_DEP_H__
+
+#include <starpu.h>
+
+#ifdef __cplusplus
+extern "C"
+{
+#endif
+
+/**
+   @defgroup API_Explicit_Dependencies Explicit Dependencies
+   @{
+*/
+
+/**
+   Declare task dependencies between a \p task and an array of tasks
+   of length \p ndeps. This function must be called prior to the
+   submission of the task, but it may called after the submission or
+   the execution of the tasks in the array, provided the tasks are
+   still valid (i.e. they were not automatically destroyed). Calling
+   this function on a task that was already submitted or with an entry
+   of \p task_array that is no longer a valid task results in an
+   undefined behaviour. If \p ndeps is 0, no dependency is added. It
+   is possible to call starpu_task_declare_deps_array() several times
+   on the same task, in this case, the dependencies are added. It is
+   possible to have redundancy in the task dependencies.
+*/
+void starpu_task_declare_deps_array(struct starpu_task *task, unsigned ndeps, struct starpu_task *task_array[]);
+
+/**
+   Declare task dependencies between a \p task and an series of \p
+   ndeps tasks, similarly to starpu_task_declare_deps_array(), but the
+   tasks are passed after \p ndeps, which indicates how many tasks \p
+   task shall be made to depend on. If \p ndeps is 0, no dependency is
+   added.
+*/
+void starpu_task_declare_deps(struct starpu_task *task, unsigned ndeps, ...);
+
+/**
+   Declare task end dependencies between a \p task and an array of
+   tasks of length \p ndeps. \p task will appear as terminated not
+   only when \p task is termination, but also when the tasks of \p
+   task_array have terminated. This function must be called prior to
+   the termination of the task, but it may called after the submission
+   or the execution of the tasks in the array, provided the tasks are
+   still valid (i.e. they were not automatically destroyed). Calling
+   this function on a task that was already terminated or with an
+   entry of \p task_array that is no longer a valid task results in an
+   undefined behaviour. If \p ndeps is 0, no dependency is added. It
+   is possible to call starpu_task_declare_end_deps_array() several
+   times on the same task, in this case, the dependencies are added.
+   It is currently not implemented to have redundancy in the task
+   dependencies.
+*/
+void starpu_task_declare_end_deps_array(struct starpu_task *task, unsigned ndeps, struct starpu_task *task_array[]);
+
+/**
+   Declare task end dependencies between a \p task and an series of \p
+   ndeps tasks, similarly to starpu_task_declare_end_deps_array(), but
+   the tasks are passed after \p ndeps, which indicates how many tasks
+   \p task 's termination shall be made to depend on. If \p ndeps is
+   0, no dependency is added.
+*/
+void starpu_task_declare_end_deps(struct starpu_task *task, unsigned ndeps, ...);
+
+/**
+   Fill \p task_array with the list of tasks which are direct children
+   of \p task. \p ndeps is the size of \p task_array.  This function
+   returns the number of direct children. \p task_array can be set to
+   <c>NULL</c> if \p ndeps is 0, which allows to compute the number of
+   children before allocating an array to store them. This function
+   can only be called if \p task has not completed yet, otherwise the
+   results are undefined. The result may also be outdated if some
+   additional dependency has been added in the meanwhile.
+*/
+int starpu_task_get_task_succs(struct starpu_task *task, unsigned ndeps, struct starpu_task *task_array[]);
+
+/**
+   Behave like starpu_task_get_task_succs(), except that it only
+   reports tasks which will go through the scheduler, thus avoiding
+   tasks with not codelet, or with explicit placement.
+*/
+int starpu_task_get_task_scheduled_succs(struct starpu_task *task, unsigned ndeps, struct starpu_task *task_array[]);
+
+/**
+   Add \p nb_deps end dependencies to the task \p t. This means the
+   task will not terminate until the required number of calls to the
+   function starpu_task_end_dep_release() has been made.
+*/
+void starpu_task_end_dep_add(struct starpu_task *t, int nb_deps);
+
+/**
+   Unlock 1 end dependency to the task \p t. This function must be
+   called after starpu_task_end_dep_add().
+*/
+void starpu_task_end_dep_release(struct starpu_task *t);
+
+/**
+   Define a task logical identifer. It is possible to associate a task
+   with a unique <em>tag</em> chosen by the application, and to
+   express dependencies between tasks by the means of those tags. To
+   do so, fill the field starpu_task::tag_id with a tag number (can be
+   arbitrary) and set the field starpu_task::use_tag to 1. If
+   starpu_tag_declare_deps() is called with this tag number, the task
+   will not be started until the tasks which holds the declared
+   dependency tags are completed.
+*/
+typedef uint64_t starpu_tag_t;
+
+/**
+   Specify the dependencies of the task identified by tag \p id. The
+   first argument specifies the tag which is configured, the second
+   argument gives the number of tag(s) on which \p id depends. The
+   following arguments are the tags which have to be terminated to
+   unlock the task. This function must be called before the associated
+   task is submitted to StarPU with starpu_task_submit().
+
+   <b>WARNING! Use with caution</b>. Because of the variable arity of
+   starpu_tag_declare_deps(), note that the last arguments must be of
+   type ::starpu_tag_t : constant values typically need to be
+   explicitly casted. Otherwise, due to integer sizes and argument
+   passing on the stack, the C compiler might consider the tag
+   <c>0x200000003</c> instead of <c>0x2</c> and <c>0x3</c> when
+   calling <c>starpu_tag_declare_deps(0x1, 2, 0x2, 0x3)</c>. Using the
+   starpu_tag_declare_deps_array() function avoids this hazard.
+
+   \code{.c}
+   //  Tag 0x1 depends on tags 0x32 and 0x52
+   starpu_tag_declare_deps((starpu_tag_t)0x1, 2, (starpu_tag_t)0x32, (starpu_tag_t)0x52);
+   \endcode
+*/
+void starpu_tag_declare_deps(starpu_tag_t id, unsigned ndeps, ...);
+
+/**
+   Similar to starpu_tag_declare_deps(), except that its does not take
+   a variable number of arguments but an \p array of tags of size \p
+   ndeps.
+
+   \code{.c}
+   // Tag 0x1 depends on tags 0x32 and 0x52
+   starpu_tag_t tag_array[2] = {0x32, 0x52};
+   starpu_tag_declare_deps_array((starpu_tag_t)0x1, 2, tag_array);
+   \endcode
+*/
+void starpu_tag_declare_deps_array(starpu_tag_t id, unsigned ndeps, starpu_tag_t *array);
+
+/**
+   Block until the task associated to tag \p id has been executed.
+   This is a blocking call which must therefore not be called within
+   tasks or callbacks, but only from the application directly. It is
+   possible to synchronize with the same tag multiple times, as long
+   as the starpu_tag_remove() function is not called. Note that it is
+   still possible to synchronize with a tag associated to a task for
+   which the strucuture starpu_task was freed (e.g. if the field
+   starpu_task::destroy was enabled).
+*/
+int starpu_tag_wait(starpu_tag_t id);
+
+/**
+   Similar to starpu_tag_wait() except that it blocks until all the \p
+   ntags tags contained in the array \p id are terminated.
+*/
+int starpu_tag_wait_array(unsigned ntags, starpu_tag_t *id);
+
+/**
+   Clear the <em>already notified</em> status of a tag which is not
+   associated with a task. Before that, calling
+   starpu_tag_notify_from_apps() again will not notify the successors.
+   After that, the next call to starpu_tag_notify_from_apps() will
+   notify the successors.
+*/
+void starpu_tag_restart(starpu_tag_t id);
+
+/**
+   Release the resources associated to tag \p id. It can be called
+   once the corresponding task has been executed and when there is no
+   other tag that depend on this tag anymore.
+*/
+void starpu_tag_remove(starpu_tag_t id);
+
+/**
+   Explicitly unlock tag \p id. It may be useful in the case of
+   applications which execute part of their computation outside StarPU
+   tasks (e.g. third-party libraries). It is also provided as a
+   convenient tool for the programmer, for instance to entirely
+   construct the task DAG before actually giving StarPU the
+   opportunity to execute the tasks. When called several times on the
+   same tag, notification will be done only on first call, thus
+   implementing "OR" dependencies, until the tag is restarted using
+   starpu_tag_restart().
+*/
+void starpu_tag_notify_from_apps(starpu_tag_t id);
+
+struct starpu_task *starpu_tag_get_task(starpu_tag_t id);
+
+/** @} */
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* __STARPU_TASK_DEP_H__ */

include/starpu_task_list.h

@@ -1,7 +1,8 @@
 /* StarPU --- Runtime system for heterogeneous multicore architectures.
  *
  * Copyright (C) 2010-2012,2014,2016,2017                 Université de Bordeaux
- * Copyright (C) 2011-2014,2017,2018,2019                      CNRS
+ * Copyright (C) 2011-2014,2017,2018,2019                 CNRS
+ * 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
@@ -18,11 +19,6 @@
 #ifndef __STARPU_TASK_LIST_H__
 #define __STARPU_TASK_LIST_H__
 
-/** @defgroup
- *
- * @{
- */
-
 #include <starpu_task.h>
 #include <starpu_util.h>
 
@@ -31,64 +27,111 @@ extern "C"
 {
 #endif
 
-	/* NOTE: this needs to have at least the same size as lists in src/common/list.h */
+/**
+   @defgroup API_Task_Lists Task Lists
+   @{
+*/
+
+/* NOTE: this needs to have at least the same size as lists in src/common/list.h */
 #ifdef BUILDING_STARPU
 #define STARPU_TASK_LIST_INLINE extern inline
 #else
+/**
+   Store a double-chained list of tasks
+*/
 struct starpu_task_list
 {
-	struct starpu_task *head;
-	struct starpu_task *tail;
+	struct starpu_task *head;  /**< head of the list */
+	struct starpu_task *tail;  /**< tail of the list */
 };
 #define STARPU_TASK_LIST_INLINE extern
 #endif
 
+/**
+   Initialize a list structure
+*/
 STARPU_TASK_LIST_INLINE
 void starpu_task_list_init(struct starpu_task_list *list);
 
+/**
+   Push \p task at the front of \p list
+*/
 STARPU_TASK_LIST_INLINE
 void starpu_task_list_push_front(struct starpu_task_list *list, struct starpu_task *task);
 
+/**
+   Push \p task at the back of \p list
+*/
 STARPU_TASK_LIST_INLINE
 void starpu_task_list_push_back(struct starpu_task_list *list, struct starpu_task *task);
 
+/**
+   Get the front of \p list (without removing it)
+*/
 STARPU_TASK_LIST_INLINE
 struct starpu_task *starpu_task_list_front(const struct starpu_task_list *list);
 
+/**
+   Get the back of \p list (without removing it)
+*/
 STARPU_TASK_LIST_INLINE
 struct starpu_task *starpu_task_list_back(const struct starpu_task_list *list);
 
+/**
+   Test if \p list is empty
+*/
 STARPU_TASK_LIST_INLINE
 int starpu_task_list_empty(const struct starpu_task_list *list);
 
+/**
+   Remove \p task from \p list
+*/
 STARPU_TASK_LIST_INLINE
 void starpu_task_list_erase(struct starpu_task_list *list, struct starpu_task *task);
 
+/**
+   Remove the element at the front of \p list
+*/
 STARPU_TASK_LIST_INLINE
 struct starpu_task *starpu_task_list_pop_front(struct starpu_task_list *list);
 
+/**
+   Remove the element at the back of \p list
+*/
 STARPU_TASK_LIST_INLINE
 struct starpu_task *starpu_task_list_pop_back(struct starpu_task_list *list);
 
+/**
+   Get the first task of \p list.
+*/
 STARPU_TASK_LIST_INLINE
 struct starpu_task *starpu_task_list_begin(const struct starpu_task_list *list);
 
+/**
+   Get the end of \p list.
+*/
 STARPU_TASK_LIST_INLINE
 struct starpu_task *starpu_task_list_end(const struct starpu_task_list *list STARPU_ATTRIBUTE_UNUSED);
 
+/**
+   Get the next task of \p list. This is not erase-safe.
+*/
 STARPU_TASK_LIST_INLINE
 struct starpu_task *starpu_task_list_next(const struct starpu_task *task);
 
+/**
+   Test whether the given task \p look is contained in the \p list.
+*/
 STARPU_TASK_LIST_INLINE
 int starpu_task_list_ismember(const struct starpu_task_list *list, const struct starpu_task *look);
 
 STARPU_TASK_LIST_INLINE
 void starpu_task_list_move(struct starpu_task_list *ldst, struct starpu_task_list *lsrc);
 
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif
 
-/** @} */
-
 #endif /* __STARPU_TASK_LIST_H__ */

include/starpu_task_util.h

@@ -19,11 +19,6 @@
 #ifndef __STARPU_TASK_UTIL_H__
 #define __STARPU_TASK_UTIL_H__
 
-/** @defgroup
- *
- * @{
- */
-
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
@@ -35,58 +30,278 @@ extern "C"
 {
 #endif
 
-void starpu_create_sync_task(starpu_tag_t sync_tag, unsigned ndeps, starpu_tag_t *deps, void (*callback)(void *), void *callback_arg);
+/**
+   @defgroup API_Insert_Task Task Insert Utility
+   @{
+*/
 
 /* NOTE: when adding a value here, please make sure to update both
  * src/util/starpu_task_insert_utils.c (in two places) and
  * mpi/src/starpu_mpi_task_insert.c and mpi/src/starpu_mpi_task_insert_fortran.c */
+
 #define STARPU_MODE_SHIFT	17
+
+/**
+   Used when calling starpu_task_insert(), must be followed by a
+   pointer to a constant value and the size of the constant
+ */
 #define STARPU_VALUE		 (1<<STARPU_MODE_SHIFT)
+
+/**
+   Used when calling starpu_task_insert(), must be followed by a
+   pointer to a callback function
+*/
 #define STARPU_CALLBACK		 (2<<STARPU_MODE_SHIFT)
+
+/**
+   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.
+*/
 #define STARPU_CALLBACK_WITH_ARG (3<<STARPU_MODE_SHIFT)
+
+/**
+   Used when calling starpu_task_insert(), must be followed by a
+   pointer to be given as an argument to the callback function
+*/
 #define STARPU_CALLBACK_ARG	 (4<<STARPU_MODE_SHIFT)
+
+/**
+   Used when calling starpu_task_insert(), must
+   be followed by a integer defining a priority level
+*/
 #define STARPU_PRIORITY		 (5<<STARPU_MODE_SHIFT)
+
 #define STARPU_EXECUTE_ON_NODE	 (6<<STARPU_MODE_SHIFT)
 #define STARPU_EXECUTE_ON_DATA	 (7<<STARPU_MODE_SHIFT)
 #define STARPU_DATA_ARRAY        (8<<STARPU_MODE_SHIFT)
 #define STARPU_DATA_MODE_ARRAY   (9<<STARPU_MODE_SHIFT)
+
+/**
+   Used when calling starpu_task_insert(), must be followed by a tag.
+*/
 #define STARPU_TAG               (10<<STARPU_MODE_SHIFT)
+
 #define STARPU_HYPERVISOR_TAG	 (11<<STARPU_MODE_SHIFT)
+
+/**
+   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.
+*/
 #define STARPU_FLOPS	         (12<<STARPU_MODE_SHIFT)
+
+/**
+   Used when calling starpu_task_insert(), must be followed by the id
+   of the scheduling context to which to submit the task to.
+*/
 #define STARPU_SCHED_CTX	 (13<<STARPU_MODE_SHIFT)
+
 #define STARPU_PROLOGUE_CALLBACK   (14<<STARPU_MODE_SHIFT)
 #define STARPU_PROLOGUE_CALLBACK_ARG (15<<STARPU_MODE_SHIFT)
 #define STARPU_PROLOGUE_CALLBACK_POP   (16<<STARPU_MODE_SHIFT)
 #define STARPU_PROLOGUE_CALLBACK_POP_ARG (17<<STARPU_MODE_SHIFT)
+
+/**
+   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)
+*/
 #define STARPU_EXECUTE_ON_WORKER (18<<STARPU_MODE_SHIFT)
 #define STARPU_EXECUTE_WHERE     (19<<STARPU_MODE_SHIFT)
+
+/**
+   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.
+*/
 #define STARPU_TAG_ONLY          (20<<STARPU_MODE_SHIFT)
+
 #define STARPU_POSSIBLY_PARALLEL    (21<<STARPU_MODE_SHIFT)
+
+/**
+   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)
+*/
 #define STARPU_WORKER_ORDER      (22<<STARPU_MODE_SHIFT)
 #define STARPU_NODE_SELECTION_POLICY (23<<STARPU_MODE_SHIFT)
+
+/**
+   Used when calling starpu_task_insert(), must be followed by a
+   char * stored in starpu_task::name.
+*/
 #define STARPU_NAME		 (24<<STARPU_MODE_SHIFT)
+
+/**
+   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)
+*/
 #define STARPU_CL_ARGS		(25<<STARPU_MODE_SHIFT)
+
+/**
+   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)
+*/
 #define STARPU_CL_ARGS_NFREE	(26<<STARPU_MODE_SHIFT)
+
+/**
+   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.
+*/
 #define STARPU_TASK_DEPS_ARRAY	(27<<STARPU_MODE_SHIFT)
+
+/**
+   Used when calling starpu_task_insert(), must be followed by an
+   integer representing a color
+*/
 #define STARPU_TASK_COLOR       (28<<STARPU_MODE_SHIFT)
+
+/**
+   Used when calling starpu_task_insert(), must be followed by an
+   array of characters representing the sequential consistency for
+   each buffer of the task.
+*/
 #define STARPU_HANDLES_SEQUENTIAL_CONSISTENCY (29<<STARPU_MODE_SHIFT)
+
+/**
+   Used when calling starpu_task_insert(), must be followed by an
+   integer stating if the task is synchronous or not
+*/
 #define STARPU_TASK_SYNCHRONOUS (30<<STARPU_MODE_SHIFT)
+
+/**
+   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.
+*/
 #define STARPU_TASK_END_DEPS_ARRAY	(31<<STARPU_MODE_SHIFT)
+
+/**
+   Used when calling starpu_task_insert(), must be followed by an
+   integer which will be given to starpu_task_end_dep_add()
+*/
 #define STARPU_TASK_END_DEP	(32<<STARPU_MODE_SHIFT)
 
 #define STARPU_SHIFTED_MODE_MAX (33<<STARPU_MODE_SHIFT)
 
+/**
+   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.
+*/
 int starpu_task_set(struct starpu_task *task, struct starpu_codelet *cl, ...);
+
+/**
+   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.
+*/
 struct starpu_task *starpu_task_build(struct starpu_codelet *cl, ...);
+
+/**
+   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.
+*/
 int starpu_task_insert(struct starpu_codelet *cl, ...);
-/* the function starpu_insert_task has the same semantics as starpu_task_insert, it is kept to avoid breaking old codes */
+
+/**
+   Similar to starpu_task_insert(). Kept to avoid breaking old codes.
+*/
 int starpu_insert_task(struct starpu_codelet *cl, ...);
 
+/**
+   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.
+*/
 void starpu_task_insert_data_make_room(struct starpu_codelet *cl, struct starpu_task *task, int *allocated_buffers, int current_buffer, int room);
+
+/**
+   Store data handle \p handle into task \p task with mode \p
+   arg_type, updating \p *allocated_buffers and \p *current_buffer
+   accordingly.
+*/
 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 \p nb_handles data handles \p handles into task \p task,
+   updating \p *allocated_buffers and \p *current_buffer accordingly.
+*/
 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 \p nb_descrs data handles described by \p descrs into task \p
+   task, updating \p *allocated_buffers and \p *current_buffer
+   accordingly.
+*/
 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);
 
+/**
+   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().
+*/
 void starpu_codelet_pack_args(void **arg_buffer, size_t *arg_buffer_size, ...);
 
 struct starpu_codelet_pack_arg_data
@@ -97,17 +312,49 @@ struct starpu_codelet_pack_arg_data
 	int nargs;
 };
 
+/**
+   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.
+*/
 void starpu_codelet_pack_arg_init(struct starpu_codelet_pack_arg_data *state);
+
+/**
+   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.
+*/
 void starpu_codelet_pack_arg(struct starpu_codelet_pack_arg_data *state, const void *ptr, size_t ptr_size);
+
+/**
+   Finish packing data, after calling starpu_codelet_pack_arg_init()
+   once and starpu_codelet_pack_arg() several times.
+*/
 void starpu_codelet_pack_arg_fini(struct starpu_codelet_pack_arg_data *state, void **cl_arg, size_t *cl_arg_size);
 
+/**
+   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.
+*/
 void starpu_codelet_unpack_args(void *cl_arg, ...);
+
+/**
+   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.
+*/
 void starpu_codelet_unpack_args_and_copyleft(void *cl_arg, void *buffer, size_t buffer_size, ...);
 
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif
 
-/** @} */
-
 #endif /* __STARPU_TASK_UTIL_H__ */

include/starpu_thread.h

@@ -16,14 +16,11 @@
  * See the GNU Lesser General Public License in COPYING.LGPL for more details.
  */
 
+// The documentation for this file is in doc/doxygen/chapters/api/threads.doxy
+
 #ifndef __STARPU_THREAD_H__
 #define __STARPU_THREAD_H__
 
-/** @defgroup
- *
- * @{
- */
-
 #include <starpu_config.h>
 #include <starpu_util.h>
 #ifdef STARPU_SIMGRID
@@ -446,6 +443,4 @@ int starpu_sem_wait(starpu_sem_t *);
 }
 #endif
 
-/** @} */
-
 #endif /* __STARPU_THREAD_H__ */

include/starpu_thread_util.h

@@ -16,14 +16,11 @@
  * See the GNU Lesser General Public License in COPYING.LGPL for more details.
  */
 
+// The documentation for this file is in doc/doxygen/chapters/api/threads.doxy
+
 #ifndef __STARPU_THREAD_UTIL_H__
 #define __STARPU_THREAD_UTIL_H__
 
-/** @defgroup
- *
- * @{
- */
-
 #include <starpu_util.h>
 #include <starpu_thread.h>
 #include <errno.h>
@@ -388,6 +385,4 @@ int _starpu_pthread_cond_timedwait(starpu_pthread_cond_t *cond, starpu_pthread_m
 } while (0)
 #endif /* _MSC_VER */
 
-/** @} */
-
 #endif /* __STARPU_THREAD_UTIL_H__ */

include/starpu_top.h

@@ -1,7 +1,7 @@
 /* StarPU --- Runtime system for heterogeneous multicore architectures.
  *
  * Copyright (C) 2011                                     Inria
- * Copyright (C) 2011-2013,2017,2019                           CNRS
+ * Copyright (C) 2011-2013,2017,2019                      CNRS
  * Copyright (C) 2011-2013                                Université de Bordeaux
  * Copyright (C) 2011                                     William Braik, Yann Courtois, Jean-Marie Couteyen, Anthony
  *
@@ -20,11 +20,6 @@
 #ifndef __STARPU_TOP_H__
 #define __STARPU_TOP_H__
 
-/** @defgroup
- *
- * @{
- */
-
 #include <starpu.h>
 #include <stdlib.h>
 #include <time.h>
@@ -34,6 +29,14 @@ extern "C"
 {
 #endif
 
+/**
+   @defgroup API_StarPUTop_Interface StarPU-Top Interface
+   @{
+*/
+
+/**
+   StarPU-Top Data type
+*/
 enum starpu_top_data_type
 {
 	STARPU_TOP_DATA_BOOLEAN,
@@ -54,6 +57,9 @@ struct starpu_top_data
 	struct starpu_top_data *next;
 };
 
+/**
+   StarPU-Top Parameter type
+*/
 enum starpu_top_param_type
 {
 	STARPU_TOP_PARAM_BOOLEAN,
@@ -68,16 +74,19 @@ struct starpu_top_param
 	const char *name;
 	enum starpu_top_param_type type;
 	void *value;
-	char **enum_values;
+	char **enum_values;  /**< only for enum type can be <c>NULL</c> */
 	int nb_values;
 	void (*callback)(struct starpu_top_param*);
-	int int_min_value;
+	int int_min_value; /**< only for integer type */
 	int int_max_value;
-	double double_min_value;
+	double double_min_value; /**< only for double type */
 	double double_max_value;
 	struct starpu_top_param *next;
 };
 
+/**
+   StarPU-Top Message type
+*/
 enum starpu_top_message_type
 {
 	TOP_TYPE_GO,
@@ -89,31 +98,132 @@ enum starpu_top_message_type
 	TOP_TYPE_UNKNOW
 };
 
+/**
+   @name Functions to call before the initialisation
+   @{
+*/
+
+/**
+   Register a data named \p data_name of type boolean. If \p active is
+   0, the value will NOT be displayed to users. Any other value will
+   make the value displayed.
+*/
 struct starpu_top_data *starpu_top_add_data_boolean(const char *data_name, int active);
+
+/**
+   Register a data named \p data_name of type integer. \p
+   minimum_value and \p maximum_value will be used to define the scale
+   in the UI. If \p active is 0, the value will NOT be displayed to
+   users. Any other value will make the value displayed.
+*/
 struct starpu_top_data *starpu_top_add_data_integer(const char *data_name, int minimum_value, int maximum_value, int active);
+
+/**
+   Register a data named \p data_name of type float. \p minimum_value
+   and \p maximum_value will be used to define the scale in the UI. If
+   \p active is 0, the value will NOT be displayed to users. Any other
+   value will make the value displayed.
+*/
 struct starpu_top_data *starpu_top_add_data_float(const char *data_name, double minimum_value, double maximum_value, int active);
 
+/**
+   Register a parameter named \p parameter_name, of type boolean. If
+   not \c NULL, the \p callback function will be called when the
+   parameter is modified by the UI.
+*/
 struct starpu_top_param *starpu_top_register_parameter_boolean(const char *param_name, int *parameter_field, void (*callback)(struct starpu_top_param*));
+
+/**
+   Register a parameter named \p param_name, of type integer. \p
+   minimum_value and \p maximum_value will be used to prevent users
+   from setting incorrect value. If not \c NULL, the \p callback
+   function will be called when the parameter is modified by the UI.
+*/
 struct starpu_top_param *starpu_top_register_parameter_integer(const char *param_name, int *parameter_field, int minimum_value, int maximum_value, void (*callback)(struct starpu_top_param*));
+
+/**
+   Register a parameter named \p param_name, of type float. \p
+   minimum_value and \p maximum_value will be used to prevent users
+   from setting incorrect value. If not \c NULL, the \p callback
+   function will be called when the parameter is modified by the UI.
+*/
 struct starpu_top_param *starpu_top_register_parameter_float(const char *param_name, double *parameter_field, double minimum_value, double maximum_value, void (*callback)(struct starpu_top_param*));
+
+/**
+   Register a parameter named \p param_name, of type enum. \p values
+   and \p nb_values will be used to prevent users from setting
+   incorrect value. If not \c NULL, the \p callback function will be
+   called when the parameter is modified by the UI.
+*/
 struct starpu_top_param *starpu_top_register_parameter_enum(const char *param_name, int *parameter_field, char **values, int nb_values, void (*callback)(struct starpu_top_param*));
 
+/** @} */
+
+/**
+   @name Initialisation
+   @{
+*/
+
+/**
+   Must be called when all parameters and data have been registered
+   AND initialised (for parameters). It will wait for a TOP to
+   connect, send initialisation sentences, and wait for the GO
+   message.
+*/
 void starpu_top_init_and_wait(const char *server_name);
 
+/** @} */
+
+/**
+   @name To call after initialisation
+   @{
+*/
+
+/**
+   Should be called after every modification of a parameter from
+   something other than starpu_top. It notices the UI that the
+   configuration has changed.
+*/
 void starpu_top_update_parameter(const struct starpu_top_param *param);
+
+/**
+   Update the boolean value of \p data to \p value the UI.
+*/
 void starpu_top_update_data_boolean(const struct starpu_top_data *data, int value);
+
+/**
+   Update the integer value of \p data to \p value the UI.
+*/
 void starpu_top_update_data_integer(const struct starpu_top_data *data, int value);
+
+/**
+   Update the float value of \p data to \p value the UI.
+*/
 void starpu_top_update_data_float(const struct starpu_top_data *data, double value);
+
+/**
+   Notify the UI that \p task is planned to run from \p start to \p
+   end, on computation-core.
+*/
 void starpu_top_task_prevision(struct starpu_task *task, int devid, unsigned long long start, unsigned long long end);
 
+/**
+   When running in debug mode, display \p message in the UI.
+*/
 void starpu_top_debug_log(const char *message);
+
+/**
+   When running in debug mode, send \p message to the UI and wait for
+   a continue message to return. The lock (which creates a stop-point)
+   should be called only by the main thread. Calling it from more than
+   one thread is not supported.
+*/
 void starpu_top_debug_lock(const char *message);
 
+/** @} */
 
 #ifdef __cplusplus
 }
 #endif
 
-/** @} */
-
 #endif /* __STARPU_TOP_H__ */

include/starpu_tree.h

@@ -19,16 +19,17 @@
 #ifndef __STARPU_TREE_H__
 #define __STARPU_TREE_H__
 
-/** @defgroup
- *
- * @{
- */
-
 #ifdef __cplusplus
 extern "C"
 {
 #endif
 
+/**
+   @defgroup API_Tree Tree
+   @brief This section describes the tree facilities provided by StarPU.
+   @{
+*/
+
 struct starpu_tree
 {
 	struct starpu_tree *nodes;
@@ -50,10 +51,10 @@ struct starpu_tree *starpu_tree_get_neighbour(struct starpu_tree *tree, struct s
 
 void starpu_tree_free(struct starpu_tree *tree);
 
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif
 
-/** @} */
-
 #endif /* __STARPU_TREE_H__ */

include/starpu_util.h

@@ -19,11 +19,6 @@
 #ifndef __STARPU_UTIL_H__
 #define __STARPU_UTIL_H__
 
-/** @defgroup
- *
- * @{
- */
-
 #include <stdio.h>
 #include <stdlib.h>
 #include <stdint.h>
@@ -45,6 +40,11 @@ extern "C"
 {
 #endif
 
+/** @defgroup
+ *
+ * @{
+ */
+
 #if defined __GNUC__ && defined __GNUC_MINOR__
 # define STARPU_GNUC_PREREQ(maj, min) \
 	((__GNUC__ << 16) + __GNUC_MINOR__ >= ((maj) << 16) + (min))
@@ -487,10 +487,10 @@ struct timespec
 #include <sys/time.h>
 #endif /* _WIN32 */
 
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif
 
-/** @} */
-
 #endif /* __STARPU_UTIL_H__ */

include/starpu_worker.h

@@ -21,11 +21,6 @@
 #ifndef __STARPU_WORKER_H__
 #define __STARPU_WORKER_H__
 
-/** @defgroup
- *
- * @{
- */
-
 #include <stdlib.h>
 #include <starpu_config.h>
 #include <starpu_thread.h>
@@ -40,6 +35,11 @@ extern "C"
 {
 #endif
 
+/** @defgroup
+ *
+ * @{
+ */
+
 enum starpu_node_kind
 {
 	STARPU_UNUSED     = 0x00,
@@ -208,10 +208,10 @@ int starpu_memory_nodes_numa_devid_to_id(unsigned id);
 
 enum starpu_node_kind starpu_node_get_kind(unsigned node);
 
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif
 
-/** @} */
-
 #endif /* __STARPU_WORKER_H__ */