/*
 * This file is part of the StarPU Handbook.
 * Copyright (C) 2009--2011  Universit@'e de Bordeaux 1
 * Copyright (C) 2010, 2011, 2012, 2013  Centre National de la Recherche Scientifique
 * Copyright (C) 2011, 2012 Institut National de Recherche en Informatique et Automatique
 * See the file version.doxy for copying conditions.
 */

/*! \defgroup Workers_Properties Workers’ Properties

\fn unsigned starpu_worker_get_count(void)
\ingroup Workers_Properties
\brief This function returns the number of workers (i.e. processing
units executing StarPU tasks). The returned value should be at most
STARPU_NMAXWORKERS. 

\fn int starpu_worker_get_count_by_type(enum starpu_worker_archtype type)
\ingroup Workers_Properties
\brief Returns the number of workers of the given type. A positive (or
NULL) value is returned in case of success, -EINVAL indicates that the
type is not valid otherwise.

\fn unsigned starpu_cpu_worker_get_count(void)
\ingroup Workers_Properties
\brief This function returns the number of CPUs controlled by StarPU. The
returned value should be at most STARPU_MAXCPUS.

\fn unsigned starpu_cuda_worker_get_count(void)
\ingroup Workers_Properties
\brief This function returns the number of CUDA devices controlled by
StarPU. The returned value should be at most STARPU_MAXCUDADEVS.

\fn unsigned starpu_opencl_worker_get_count(void)
\ingroup Workers_Properties
\brief This function returns the number of OpenCL devices controlled by
StarPU. The returned value should be at most STARPU_MAXOPENCLDEVS.

\fn int starpu_worker_get_id (void)
\ingroup Workers_Properties
\brief This function returns the identifier of the current worker, i.e
the one associated to the calling thread. The returned value is either
-1 if the current 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 starpu_worker_get_count() - 1.

\fn int starpu_worker_get_ids_by_type(enum starpu_worker_archtype type, int *workerids, int maxsize)
\ingroup Workers_Properties
\brief This function gets the list of identifiers of workers with the
given type. It fills the workerids array with the identifiers of the
workers that have the type indicated in the first argument. The
maxsize argument indicates the size of the workids array. The returned
value gives the number of identifiers that were put in the array.
-ERANGE is returned is maxsize is lower than the number of workers
with the appropriate type: in that case, the array is filled with the
maxsize first elements. To avoid such overflows, the value of maxsize
can be chosen by the means of the starpu_worker_get_count_by_type
function, or by passing a value greater or equal to
STARPU_NMAXWORKERS.

\fn int starpu_worker_get_by_type(enum starpu_worker_archtype type, int num)
\ingroup Workers_Properties
\brief This returns the identifier of the num-th worker that has the
specified type type. If there are no such worker, -1 is returned.

\fn int starpu_worker_get_by_devid(enum starpu_worker_archtype type, int devid)
\ingroup Workers_Properties
\brief This returns the identifier of the worker that has the specified type
type and devid devid (which may not be the n-th, if some devices are
skipped for instance). If there are no such worker, -1 is returned.

\fn int starpu_worker_get_devid(int id)
\ingroup Workers_Properties
\brief This function returns the device id of the given worker. The
worker should be identified with the value returned by the
starpu_worker_get_id() function. In the case of a CUDA worker, this
device identifier is the logical device identifier exposed by CUDA
(used by the cudaGetDevice function for instance). The device
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
OS or by the hwloc library in case it is available.

\fn enum starpu_worker_archtype starpu_worker_get_type(int id)
\ingroup Workers_Properties
\brief This function returns the type of processing unit associated to
a worker. The worker identifier is a value returned by the
starpu_worker_get_id() function). The returned value indicates the
architecture of the worker: STARPU_CPU_WORKER for a CPU core,
STARPU_CUDA_WORKER for a CUDA device, and STARPU_OPENCL_WORKER for a
OpenCL device. The value returned for an invalid identifier is
unspecified.

\fn void starpu_worker_get_name(int id, char *dst, size_t maxlen)
\ingroup Workers_Properties
\brief This function allows to get the name of a given worker. StarPU
associates a unique human readable string to each processing unit.
This function copies at most the maxlen first bytes of the unique
string associated to a worker identified by its identifier id into the
dst buffer. The caller is responsible for ensuring that the dst is a
valid pointer to a buffer of maxlen bytes at least. Calling this
function on an invalid identifier results in an unspecified behaviour.

\fn unsigned starpu_worker_get_memory_node(unsigned workerid)
\ingroup Workers_Properties
\brief This function returns the identifier of the memory node
associated to the worker identified by workerid.

\fn enum starpu_node_kind starpu_node_get_kind(unsigned node)
\ingroup Workers_Properties
\brief Returns the type of the given node as defined by
::starpu_node_kind. For example, when defining a new data interface,
this function should be used in the allocation function to determine
on which device the memory needs to be allocated.

*/