Browse Source

doc: small additions

Nathalie Furmento 6 years ago
parent
commit
fd5282f203

+ 3 - 4
doc/doxygen/chapters/350_scheduling_policy_definition.doxy

@@ -73,7 +73,7 @@ if (task->cl)
 
 
 Task queues can be implemented with the starpu_task_list functions.
 Task queues can be implemented with the starpu_task_list functions.
 
 
-Access to the hwloc topology is available with starpu_worker_get_hwloc_obj().
+Access to the \c hwloc topology is available with starpu_worker_get_hwloc_obj().
 
 
 \section DefiningANewBasicSchedulingPolicy Defining A New Basic Scheduling Policy
 \section DefiningANewBasicSchedulingPolicy Defining A New Basic Scheduling Policy
 
 
@@ -315,8 +315,7 @@ their task on the same target)
 
 
 \subsubsection ImplementAModularizedScheduler Implementing a Modularized Scheduler
 \subsubsection ImplementAModularizedScheduler Implementing a Modularized Scheduler
 
 
-The following code shows how the Tree-Eager-Prefetching Scheduler
+The following code shows how to implement a Tree-Eager-Prefetching Scheduler.
-shown in Section \ref ExampleTreeEagerPrefetchingStrategy can be implemented :
 
 
 \code{.c}
 \code{.c}
 static void initialize_eager_prefetching_center_policy(unsigned sched_ctx_id)
 static void initialize_eager_prefetching_center_policy(unsigned sched_ctx_id)
@@ -504,7 +503,7 @@ queue of the Component, and give it to the calling Component which asks for it.
 
 
 
 
 The Tree-Eager-Prefetching Scheduler shown in Section
 The Tree-Eager-Prefetching Scheduler shown in Section
-\ref ExampleTreeEagerPrefetchingStrategy follows the previous assumptions :
+\ref ImplementAModularizedScheduler follows the previous assumptions :
 
 
 <pre>
 <pre>
                                   starpu_push_task
                                   starpu_push_task

+ 12 - 0
doc/doxygen/chapters/api/codelet_and_tasks.doxy

@@ -882,6 +882,18 @@ starpu_codelet::nodes or the \p i -th element of the field
 starpu_codelet::dyn_nodes
 starpu_codelet::dyn_nodes
 (see \ref SettingManyDataHandlesForATask)
 (see \ref SettingManyDataHandlesForATask)
 
 
+\def STARPU_TASK_TYPE_NORMAL
+\ingroup API_Codelet_And_Tasks
+todo
+
+\def STARPU_TASK_TYPE_INTERNAL
+\ingroup API_Codelet_And_Tasks
+todo
+
+\def STARPU_TASK_TYPE_DATA_ACQUIRE
+\ingroup API_Codelet_And_Tasks
+todo
+
 \fn struct starpu_task *starpu_task_create(void)
 \fn struct starpu_task *starpu_task_create(void)
 \ingroup API_Codelet_And_Tasks
 \ingroup API_Codelet_And_Tasks
 Allocate a task structure and initialize it with default
 Allocate a task structure and initialize it with default

+ 2 - 3
doc/doxygen/chapters/api/scheduling_contexts.doxy

@@ -1,7 +1,7 @@
 /* StarPU --- Runtime system for heterogeneous multicore architectures.
 /* StarPU --- Runtime system for heterogeneous multicore architectures.
  *
  *
  * Copyright (C) 2011-2013,2016,2017                      Inria
  * Copyright (C) 2011-2013,2016,2017                      Inria
- * Copyright (C) 2010-2018                                CNRS
+ * Copyright (C) 2010-2019                                CNRS
  * Copyright (C) 2009-2011,2014,2016                      Université de Bordeaux
  * Copyright (C) 2009-2011,2014,2016                      Université de Bordeaux
  * Copyright (C) 2016                                     Uppsala University
  * Copyright (C) 2016                                     Uppsala University
  *
  *
@@ -110,8 +110,7 @@ maximum scheduler priority value.
 
 
 \def STARPU_SCHED_CTX_AWAKE_WORKERS
 \def STARPU_SCHED_CTX_AWAKE_WORKERS
 \ingroup API_Scheduling_Contexts
 \ingroup API_Scheduling_Contexts
-Used when calling starpu_sched_ctx_create() to specify a
+Used when calling starpu_sched_ctx_create() to specify ???
-pointer to a scheduling policy
 
 
 \def STARPU_SCHED_CTX_POLICY_INIT
 \def STARPU_SCHED_CTX_POLICY_INIT
 \ingroup API_Scheduling_Contexts
 \ingroup API_Scheduling_Contexts

+ 69 - 37
doc/doxygen/chapters/api/workers.doxy

@@ -1,7 +1,7 @@
 /* StarPU --- Runtime system for heterogeneous multicore architectures.
 /* StarPU --- Runtime system for heterogeneous multicore architectures.
  *
  *
  * Copyright (C) 2011-2013,2017                           Inria
  * Copyright (C) 2011-2013,2017                           Inria
- * Copyright (C) 2010-2017                                CNRS
+ * Copyright (C) 2010-2017, 2019                          CNRS
  * Copyright (C) 2009-2011,2014,2016-2019                 Université de Bordeaux
  * Copyright (C) 2009-2011,2014,2016-2019                 Université de Bordeaux
  *
  *
  * StarPU is free software; you can redistribute it and/or modify
  * StarPU is free software; you can redistribute it and/or modify
@@ -140,6 +140,30 @@ Structure needed to iterate on the collection
     The index of the current worker in the collection, needed when
     The index of the current worker in the collection, needed when
     iterating on the collection.
     iterating on the collection.
 
 
+\fn unsigned starpu_worker_get_sched_ctx_id_stream(unsigned stream_workerid)
+\ingroup API_Workers_Properties
+todo
+
+\fn unsigned starpu_worker_get_sched_ctx_list(int worker, unsigned **sched_ctx)
+\ingroup API_Workers_Properties
+todo
+
+\fn int starpu_worker_get_stream_workerids(unsigned devid, int *workerids, enum starpu_worker_archtype type)
+\ingroup API_Workers_Properties
+todo
+
+\fn unsigned starpu_worker_is_blocked_in_parallel(int workerid)
+\ingroup API_Workers_Properties
+todo
+
+\fn unsigned starpu_worker_is_slave_somewhere(int workerid)
+\ingroup API_Workers_Properties
+todo
+
+\fn unsigned starpu_worker_is_combined_worker(int id)
+\ingroup API_Workers_Properties
+todo
+
 \fn unsigned starpu_worker_get_count(void)
 \fn unsigned starpu_worker_get_count(void)
 \ingroup API_Workers_Properties
 \ingroup API_Workers_Properties
 Return the number of workers (i.e. processing units executing StarPU
 Return the number of workers (i.e. processing units executing StarPU
@@ -182,10 +206,10 @@ Return the number of OpenCL devices controlled by StarPU. The returned value sho
 \fn int starpu_worker_get_id(void)
 \fn int starpu_worker_get_id(void)
 \ingroup API_Workers_Properties
 \ingroup API_Workers_Properties
 Return the identifier of the current worker, i.e the one associated to
 Return the identifier of the current worker, i.e the one associated to
-the calling thread. The returned value is either -1 if the current
+the calling thread. The returned value is either \c -1 if the current
 context is not a StarPU worker (i.e. when called from the application
 context is not a StarPU worker (i.e. when called from the application
-outside a task or a callback), or an integer between 0 and
+outside a task or a callback), or an integer between \c 0 and
-starpu_worker_get_count() - 1.
+starpu_worker_get_count() - \c 1.
 
 
 \fn unsigned starpu_worker_get_id_check(void)
 \fn unsigned starpu_worker_get_id_check(void)
 \ingroup API_Workers_Properties
 \ingroup API_Workers_Properties
@@ -214,7 +238,7 @@ specified \p type. If there is no such worker, -1 is returned.
 \ingroup API_Workers_Properties
 \ingroup API_Workers_Properties
 Return the identifier of the worker that has the specified \p type
 Return the identifier of the worker that has the specified \p type
 and device id \p devid (which may not be the n-th, if some
 and device id \p devid (which may not be the n-th, if some
-devices are skipped for instance). If there is no such worker, -1 is
+devices are skipped for instance). If there is no such worker, \c -1 is
 returned.
 returned.
 
 
 \fn int starpu_worker_get_devid(int id)
 \fn int starpu_worker_get_devid(int id)
@@ -228,11 +252,19 @@ identifier of a CPU worker is the logical identifier of the core on
 which the worker was bound; this identifier is either provided by the
 which the worker was bound; this identifier is either provided by the
 OS or by the library <c>hwloc</c> in case it is available.
 OS or by the library <c>hwloc</c> in case it is available.
 
 
+\fn int starpu_worker_get_devids(enum starpu_worker_archtype type, int *devids, int num)
+\ingroup API_Workers_Properties
+todo
+
+\fn int starpu_worker_get_bindid(int workerid)
+\ingroup API_Workers_Properties
+todo
+
 \fn enum starpu_worker_archtype starpu_worker_get_type(int id)
 \fn enum starpu_worker_archtype starpu_worker_get_type(int id)
 \ingroup API_Workers_Properties
 \ingroup API_Workers_Properties
 Return the type of processing unit associated to the worker \p id. The
 Return the type of processing unit associated to the worker \p id. The
 worker identifier is a value returned by the function
 worker identifier is a value returned by the function
-starpu_worker_get_id()). The returned value indicates the architecture
+starpu_worker_get_id()). The return value indicates the architecture
 of the worker: ::STARPU_CPU_WORKER for a CPU core,
 of the worker: ::STARPU_CPU_WORKER for a CPU core,
 ::STARPU_CUDA_WORKER for a CUDA device, and ::STARPU_OPENCL_WORKER for
 ::STARPU_CUDA_WORKER for a CUDA device, and ::STARPU_OPENCL_WORKER for
 a OpenCL device. The value returned for an invalid identifier is
 a OpenCL device. The value returned for an invalid identifier is
@@ -291,18 +323,18 @@ worker state, even though it is performing a scheduling operation.
 Must be called by a worker before performing a potentially blocking
 Must be called by a worker before performing a potentially blocking
 call such as acquiring a mutex other than its own sched_mutex. This
 call such as acquiring a mutex other than its own sched_mutex. This
 function increases \c state_relax_refcnt from the current worker. No
 function increases \c state_relax_refcnt from the current worker. No
-more than <c>UINT_MAX-1</c> nested relax_on calls should performed on
+more than <c>UINT_MAX-1</c> nested starpu_worker_relax_on() calls should performed on
-the same worker. This function is automatically called by \ref
+the same worker. This function is automatically called by 
-starpu_worker_lock to relax the caller worker state while attempting
+starpu_worker_lock() to relax the caller worker state while attempting
-to lock the targer worker.
+to lock the target worker.
 
 
 \fn void starpu_worker_relax_off(void)
 \fn void starpu_worker_relax_off(void)
 \ingroup API_Workers_Properties
 \ingroup API_Workers_Properties
 Must be called after a potentially blocking call is complete, to
 Must be called after a potentially blocking call is complete, to
-restore the relax state in place before the corresponding relax_on.
+restore the relax state in place before the corresponding starpu_worker_relax_on().
-Decreases \c state_relax_refcnt. Calls to \ref starpu_worker_relax_on
+Decreases \c state_relax_refcnt. Calls to starpu_worker_relax_on()
-and \c starpu_worker_relax_off must be well parenthesized. This
+and starpu_worker_relax_off() must be properly paired. This
-function is automatically called by \ref starpu_worker_unlock after the
+function is automatically called by starpu_worker_unlock() after the
 target worker has been unlocked.
 target worker has been unlocked.
 
 
 \fn int starpu_worker_get_relax_state(void)
 \fn int starpu_worker_get_relax_state(void)
@@ -313,22 +345,22 @@ otherwise.
 \fn void starpu_worker_lock(int workerid)
 \fn void starpu_worker_lock(int workerid)
 \ingroup API_Workers_Properties
 \ingroup API_Workers_Properties
 Acquire the sched mutex of \p workerid. If the caller is a worker,
 Acquire the sched mutex of \p workerid. If the caller is a worker,
-distinct from \p workerid, the caller worker automatically enter relax
+distinct from \p workerid, the caller worker automatically enters a relax
 state while acquiring the target worker lock.
 state while acquiring the target worker lock.
 
 
 \fn int starpu_worker_trylock(int workerid)
 \fn int starpu_worker_trylock(int workerid)
 \ingroup API_Workers_Properties
 \ingroup API_Workers_Properties
 Attempt to acquire the sched mutex of \p workerid. Returns \c 0 if
 Attempt to acquire the sched mutex of \p workerid. Returns \c 0 if
 successful, \c !0 if \p workerid sched mutex is held or the
 successful, \c !0 if \p workerid sched mutex is held or the
-corresponding worker is not in relaxed stated.
+corresponding worker is not in a relax state.
 If the caller is a worker, distinct from \p workerid, the caller
 If the caller is a worker, distinct from \p workerid, the caller
-worker automatically enter relax state if successfully acquiring the target
+worker automatically enters relax state if successfully acquiring the target
 worker lock.
 worker lock.
 
 
 \fn void starpu_worker_unlock(int workerid)
 \fn void starpu_worker_unlock(int workerid)
 \ingroup API_Workers_Properties
 \ingroup API_Workers_Properties
 Release the previously acquired sched mutex of \p workerid. Restore
 Release the previously acquired sched mutex of \p workerid. Restore
-the relaxed state of the caller worker if needed.
+the relax state of the caller worker if needed.
 
 
 \fn void starpu_worker_lock_self(void)
 \fn void starpu_worker_lock_self(void)
 \ingroup API_Workers_Properties
 \ingroup API_Workers_Properties
@@ -340,28 +372,22 @@ Release the current worker sched mutex.
 
 
 \fn int starpu_wake_worker_relax(int workerid)
 \fn int starpu_wake_worker_relax(int workerid)
 \ingroup API_Workers_Properties
 \ingroup API_Workers_Properties
-Wake up \p workerid while temporarily entering the current worker relaxed state
+Wake up \p workerid while temporarily entering the current worker relax state
-if needed during the waiting process. Returns 1 if \p workerid has been woken
+if needed during the waiting process. Return 1 if \p workerid has been woken
-up or its state_keep_awake flag has been set to 1, and 0 otherwise (if \p
+up or its state_keep_awake flag has been set to \c 1, and \c 0 otherwise (if \p
 workerid was not in the STATE_SLEEPING or in the STATE_SCHEDULING).
 workerid was not in the STATE_SLEEPING or in the STATE_SCHEDULING).
 
 
 \fn int starpu_wake_worker_relax_light(int workerid)
 \fn int starpu_wake_worker_relax_light(int workerid)
 \ingroup API_Workers_Properties
 \ingroup API_Workers_Properties
 This is a light version of starpu_wake_worker_relax() which, when possible,
 This is a light version of starpu_wake_worker_relax() which, when possible,
-speculatively sets keep_awake on the target worker without waiting that worker
+speculatively set keep_awake on the target worker without waiting for the worker
-to enter the relaxed state.
+to enter the relax state.
-
-\fn hwloc_cpuset_t starpu_worker_get_hwloc_cpuset(int workerid)
-\ingroup API_Workers_Properties
-If StarPU was compiled with hwloc support, returns a duplicate of the
-hwloc cpuset associated with the worker \p workerid. The returned cpuset is obtained
-from a \c hwloc_bitmap_dup() function call. It must be freed by the caller
-using \c hwloc_bitmap_free().
 
 
-\fn hwloc_obj_t starpu_-worker_get_hwloc_obj(int workerid)
+\fn void starpu_worker_set_waking_up_callback(void (*callback)(unsigned workerid))
 \ingroup API_Workers_Properties
 \ingroup API_Workers_Properties
-If StarPU was compiled with hwloc support, returns the HWLOC object corresponding to 
+If StarPU was compiled with blocking drivers support and worker callbacks support
-the worker \p workerid.
+enabled, allow to specify an external resource manager callback to be notified
+about workers waking-up.
 
 
 \fn void starpu_worker_set_going_to_sleep_callback(void (*callback)(unsigned workerid))
 \fn void starpu_worker_set_going_to_sleep_callback(void (*callback)(unsigned workerid))
 \ingroup API_Workers_Properties
 \ingroup API_Workers_Properties
@@ -369,10 +395,16 @@ If StarPU was compiled with blocking drivers support and worker callbacks suppor
 enabled, allow to specify an external resource manager callback to be notified
 enabled, allow to specify an external resource manager callback to be notified
 about workers going to sleep.
 about workers going to sleep.
 
 
-\fn void starpu_worker_set_waking_up_callback(void (*callback)(unsigned workerid))
+\fn hwloc_cpuset_t starpu_worker_get_hwloc_cpuset(int workerid)
 \ingroup API_Workers_Properties
 \ingroup API_Workers_Properties
-If StarPU was compiled with blocking drivers support and worker callbacks support
+If StarPU was compiled with \c hwloc support, return a duplicate of the
-enabled, allow to specify an external resource manager callback to be notified
+\c hwloc cpuset associated with the worker \p workerid. The returned cpuset is obtained
-about workers waking-up.
+from a \c hwloc_bitmap_dup() function call. It must be freed by the caller
+using \c hwloc_bitmap_free().
+
+\fn hwloc_obj_t starpu_worker_get_hwloc_obj(int workerid)
+\ingroup API_Workers_Properties
+If StarPU was compiled with \c hwloc support, return the \c hwloc object corresponding to 
+the worker \p workerid.
 
 
 */
 */