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

/*
 * This file is part of the StarPU Handbook.
 * Copyright (C) 2009--2011  Universit@'e de Bordeaux
 * Copyright (C) 2010, 2011, 2012, 2013, 2014, 2016, 2017  CNRS
 * Copyright (C) 2011, 2012, 2017  INRIA
 * See the file version.doxy for copying conditions.
 */

/*! \defgroup API_Workers_Properties Workers’ Properties

\def STARPU_NMAXWORKERS
\ingroup API_Workers_Properties
Define the maximum number of workers managed by StarPU.

\def STARPU_MAXCPUS
\ingroup API_Workers_Properties
Define the maximum number of CPU workers managed by StarPU. The default value can be modified at
configure by using the option \ref enable-maxcpus "--enable-maxcpus".

\def STARPU_MAXNODES
\ingroup API_Workers_Properties
Define the maximum number of memory nodes managed by StarPU. The default value can be modified at
configure by using the option \ref enable-maxnodes "--enable-maxnodes". Reducing it allows to
considerably reduce memory used by StarPU data structures.

\enum starpu_node_kind
\ingroup API_Workers_Properties
TODO
\var starpu_node_kind::STARPU_UNUSED
\ingroup API_Workers_Properties
TODO
\ingroup API_Workers_Properties
\var starpu_node_kind::STARPU_CPU_RAM
\ingroup API_Workers_Properties
TODO
\var starpu_node_kind::STARPU_CUDA_RAM
\ingroup API_Workers_Properties
TODO
\var starpu_node_kind::STARPU_OPENCL_RAM
\ingroup API_Workers_Properties
TODO
\var starpu_node_kind::STARPU_DISK_RAM
\ingroup API_Workers_Properties
TODO
\var starpu_node_kind::STARPU_MIC_RAM
\ingroup API_Workers_Properties
TODO
\var starpu_node_kind::STARPU_SCC_RAM
\ingroup API_Workers_Properties
This node kind is not used anymore, but implementations in interfaces
will be useful for MPI.
\var starpu_node_kind::STARPU_SCC_SHM
\ingroup API_Workers_Properties
TODO
\var starpu_node_kind::STARPU_MPI_MS_RAM
\ingroup API_Workers_Properties
TODO

\enum starpu_worker_archtype
\ingroup API_Workers_Properties
Worker Architecture Type
\var starpu_worker_archtype::STARPU_ANY_WORKER
\ingroup API_Workers_Properties
any worker, used in the hypervisor
\var starpu_worker_archtype::STARPU_CPU_WORKER
\ingroup API_Workers_Properties
CPU core
\var starpu_worker_archtype::STARPU_CUDA_WORKER
\ingroup API_Workers_Properties
NVIDIA CUDA device
\var starpu_worker_archtype::STARPU_OPENCL_WORKER
\ingroup API_Workers_Properties
OpenCL device
\var starpu_worker_archtype::STARPU_MIC_WORKER
\ingroup API_Workers_Properties
Intel MIC device
\var starpu_worker_archtype::STARPU_SCC_WORKER
\ingroup API_Workers_Properties
Intel SCC device
\var starpu_worker_archtype::STARPU_MPI_MS_WORKER
\ingroup API_Workers_Properties
MPI Slave device


\struct starpu_worker_collection
\ingroup API_Workers_Properties
A scheduling context manages a collection of workers that can
be memorized using different data structures. Thus, a generic
structure is available in order to simplify the choice of its type.
Only the list data structure is available but further data
structures(like tree) implementations are foreseen.
\var void *starpu_worker_collection::workerids
        The workerids managed by the collection
\var unsigned starpu_worker_collection::nworkers
        The number of workers in the collection
\var enum starpu_worker_collection_type starpu_worker_collection::type
        The type of structure (currently ::STARPU_WORKER_LIST is the only one available)
\var unsigned (*starpu_worker_collection::has_next)(struct starpu_worker_collection *workers, struct starpu_sched_ctx_iterator *it)
        Checks if there is another element in collection
\var int (*starpu_worker_collection::get_next)(struct starpu_worker_collection *workers, struct starpu_sched_ctx_iterator *it)
        return the next element in the collection
\var int (*starpu_worker_collection::add)(struct starpu_worker_collection *workers, int worker)
        add a new element in the collection
\var int (*starpu_worker_collection::remove)(struct starpu_worker_collection *workers, int worker)
        remove an element from the collection
\var void (*starpu_worker_collection::init)(struct starpu_worker_collection *workers)
        Initialize the collection
\var void (*starpu_worker_collection::deinit)(struct starpu_worker_collection *workers)
        Deinitialize the colection
\var void (*starpu_worker_collection::init_iterator)(struct starpu_worker_collection *workers, struct starpu_sched_ctx_iterator *it)
        Initialize the cursor if there is one

\enum starpu_worker_collection_type
\ingroup API_Workers_Properties
Types of structures the worker collection can implement
\var starpu_worker_collection_type::STARPU_WORKER_LIST
\ingroup API_Workers_Properties
The collection is an array

\struct starpu_sched_ctx_iterator
\ingroup API_Workers_Properties
Structure needed to iterate on the collection
\var int starpu_sched_ctx_iterator::cursor
The index of the current worker in the collection, needed when iterating on
the collection.


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

\fn int starpu_worker_get_count_by_type(enum starpu_worker_archtype type)
\ingroup API_Workers_Properties
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 API_Workers_Properties
This function returns the number of CPUs controlled by StarPU. The
returned value should be at most \ref STARPU_MAXCPUS.

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

\fn unsigned starpu_mic_worker_get_count(void)
\ingroup API_Workers_Properties
This function returns the number of MIC workers controlled by StarPU.

\fn unsigned starpu_mic_device_get_count(void)
\ingroup API_Workers_Properties
This function returns the number of MIC devices controlled by StarPU.
The returned value should be at most \ref STARPU_MAXMICDEVS.

\fn unsigned starpu_mpi_ms_worker_get_count(void)
\ingroup API_Workers_Properties
This function returns the number of MPI Master Slave workers controlled by StarPU.

\fn unsigned starpu_scc_worker_get_count(void)
\ingroup API_Workers_Properties
This function returns the number of SCC devices controlled by StarPU.
The returned value should be at most \ref STARPU_MAXSCCDEVS.

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

\fn int starpu_worker_get_id(void)
\ingroup API_Workers_Properties
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 unsigned starpu_worker_get_id_check(void)
\ingroup API_Workers_Properties
This is the same as starpu_worker_get_id, but aborts when called from outside a
worker (i.e. when starpu_worker_get_id() would return -1).

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

\fn int starpu_worker_get_by_type(enum starpu_worker_archtype type, int num)
\ingroup API_Workers_Properties
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 API_Workers_Properties
This returns the identifier of the worker that has the specified type
\p type and device id \p 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 API_Workers_Properties
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 function cudaGetDevice() 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 library <c>hwloc</c> in case it is available.

\fn enum starpu_worker_archtype starpu_worker_get_type(int id)
\ingroup API_Workers_Properties
This function returns the type of processing unit associated to
a worker. The worker identifier is a value returned by the function
starpu_worker_get_id()). 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 API_Workers_Properties
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 \p dst is a
valid pointer to a buffer of \p 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 API_Workers_Properties
This function returns the identifier of the memory node
associated to the worker identified by \p workerid.

\fn enum starpu_node_kind starpu_node_get_kind(unsigned node)
\ingroup API_Workers_Properties
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.

\fn char *starpu_worker_get_type_as_string(enum starpu_worker_archtype type)
\ingroup API_Workers_Properties
Returns the given worker type as a string.

*/