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

/* StarPU --- Runtime system for heterogeneous multicore architectures.
 *
 * Copyright (C) 2011-2013,2017                           Inria
 * Copyright (C) 2010-2017, 2019                          CNRS
 * Copyright (C) 2009-2011,2014,2016-2019                 Université de Bordeaux
 *
 * 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_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_MAXNUMANODES
\ingroup API_Workers_Properties
Define the maximum number of NUMA nodes managed by StarPU. The default value can be modified at
configure by using the option \ref enable-maxnumanodes "--enable-maxnumanodes".

\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
    TODO
\var starpu_node_kind::STARPU_CPU_RAM
    TODO
\var starpu_node_kind::STARPU_CUDA_RAM
    TODO
\var starpu_node_kind::STARPU_OPENCL_RAM
    TODO
\var starpu_node_kind::STARPU_DISK_RAM
    TODO
\var starpu_node_kind::STARPU_MIC_RAM
    TODO
\var starpu_node_kind::STARPU_SCC_RAM
    This node kind is not used anymore, but implementations in
    interfaces will be useful for MPI.
\var starpu_node_kind::STARPU_SCC_SHM
    TODO
\var starpu_node_kind::STARPU_MPI_MS_RAM
    TODO

\enum starpu_worker_archtype
\ingroup API_Workers_Properties
Worker Architecture Type
\var starpu_worker_archtype::STARPU_ANY_WORKER
    any worker, used in the hypervisor
\var starpu_worker_archtype::STARPU_CPU_WORKER
    CPU core
\var starpu_worker_archtype::STARPU_CUDA_WORKER
    NVIDIA CUDA device
\var starpu_worker_archtype::STARPU_OPENCL_WORKER
    OpenCL device
\var starpu_worker_archtype::STARPU_MIC_WORKER
    Intel MIC device
\var starpu_worker_archtype::STARPU_SCC_WORKER
    Intel SCC device
\var starpu_worker_archtype::STARPU_MPI_MS_WORKER
    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 void *starpu_worker_collection::collection_private
        todo
\var void *starpu_worker_collection::unblocked_workers
        todo
\var unsigned starpu_worker_collection::nunblocked_workers
        todo
\var void *starpu_worker_collection::masters
        todo
\var unsigned starpu_worker_collection::nmasters
        todo
\var char starpu_worker_collection::present[STARPU_NMAXWORKERS]
        todo
\var char starpu_worker_collection::is_unblocked[STARPU_NMAXWORKERS]
        todo
\var char starpu_worker_collection::is_master[STARPU_NMAXWORKERS]
        todo
\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
\var unsigned (*starpu_worker_collection::has_next)(struct starpu_worker_collection *workers, struct starpu_sched_ctx_iterator *it)
        Check 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
\var void (*starpu_worker_collection::init_iterator_for_parallel_tasks)(struct starpu_worker_collection *workers, struct starpu_sched_ctx_iterator *it, struct starpu_task *task);
        todo

\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
    The collection is an array
\var starpu_worker_collection_type::STARPU_WORKER_TREE
    The collection is a tree

\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_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)
\ingroup API_Workers_Properties
Return the number of workers (i.e. processing units executing StarPU
tasks). The return 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
Return the number of workers of \p type. A positive (or
<c>NULL</c>) value is returned in case of success, <c>-EINVAL</c>
indicates that \p type is not valid otherwise.

\fn unsigned starpu_cpu_worker_get_count(void)
\ingroup API_Workers_Properties
Return the number of CPUs controlled by StarPU. The return value should be at most \ref STARPU_MAXCPUS.

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

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

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

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

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

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

\fn int starpu_worker_get_id(void)
\ingroup API_Workers_Properties
Return the identifier of the current worker, i.e the one associated to
the calling thread. The return value is either \c -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 \c 0 and
starpu_worker_get_count() - \c 1.

\fn unsigned starpu_worker_get_id_check(void)
\ingroup API_Workers_Properties
Similar to starpu_worker_get_id(), but abort when called from outside
a worker (i.e. when starpu_worker_get_id() would return \c -1).

\fn unsigned starpu_worker_get_ids_by_type(enum starpu_worker_archtype type, int *workerids, unsigned maxsize)
\ingroup API_Workers_Properties
Get the list of identifiers of workers of \p type. Fill the array \p
workerids with the identifiers of the \p workers. The argument \p
maxsize indicates the size of the array \p workerids. The return
value gives the number of identifiers that were put in the array.
<c>-ERANGE</c> 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
Return the identifier of the \p num -th worker that has the
specified \p type. If there is no such worker, -1 is returned.

\fn int starpu_worker_get_by_devid(enum starpu_worker_archtype type, int devid)
\ingroup API_Workers_Properties
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
devices are skipped for instance). If there is no such worker, \c -1 is
returned.

\fn int starpu_worker_get_devid(int id)
\ingroup API_Workers_Properties
Return the device id of the worker \p id. 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 \c 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 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)
\ingroup API_Workers_Properties
Return the type of processing unit associated to the worker \p id. The
worker identifier is a value returned by the function
starpu_worker_get_id()). The return 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 return value for an invalid identifier is
unspecified.

\fn void starpu_worker_get_name(int id, char *dst, size_t maxlen)
\ingroup API_Workers_Properties
Allow to get the name of the worker \p id. StarPU associates a unique
human readable string to each processing unit. This function copies at
most the \p maxlen first bytes of the unique string associated to the
worker \p id into the \p 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 void starpu_worker_display_names(FILE *output, enum starpu_worker_archtype type)
\ingroup API_Workers_Properties
Display on \p output the list (if any) of all the workers of the given
\p type.

\fn unsigned starpu_worker_get_memory_node(unsigned workerid)
\ingroup API_Workers_Properties
Return 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
Return the type of \p 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 int starpu_memory_nodes_numa_id_to_devid(int osid)
\ingroup API_Workers_Properties
Return the identifier of the memory node associated to the NUMA
node identified by \p osid by the Operating System.

\fn int starpu_memory_nodes_numa_devid_to_id(unsigned id);
\ingroup API_Workers_Properties
Return the Operating System identifier of the memory node
whose StarPU identifier is \p id.

\fn char *starpu_worker_get_type_as_string(enum starpu_worker_archtype type)
\ingroup API_Workers_Properties
Return worker \p type as a string.

\fn int starpu_worker_sched_op_pending(void)
\ingroup API_Workers_Properties
Return \c !0 if current worker has a scheduling operation in progress,
and \c 0 otherwise.

\fn void starpu_worker_relax_on(void)
\ingroup API_Workers_Properties
Allow other threads and workers to temporarily observe the current
worker state, even though it is performing a scheduling operation.
Must be called by a worker before performing a potentially blocking
call such as acquiring a mutex other than its own sched_mutex. This
function increases \c state_relax_refcnt from the current worker. No
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 
starpu_worker_lock() to relax the caller worker state while attempting
to lock the target worker.

\fn void starpu_worker_relax_off(void)
\ingroup API_Workers_Properties
Must be called after a potentially blocking call is complete, to
restore the relax state in place before the corresponding starpu_worker_relax_on().
Decreases \c state_relax_refcnt. Calls to starpu_worker_relax_on()
and starpu_worker_relax_off() must be properly paired. This
function is automatically called by starpu_worker_unlock() after the
target worker has been unlocked.

\fn int starpu_worker_get_relax_state(void)
\ingroup API_Workers_Properties
Returns \c !0 if the current worker \c state_relax_refcnt!=0 and \c 0
otherwise.

\fn void starpu_worker_lock(int workerid)
\ingroup API_Workers_Properties
Acquire the sched mutex of \p workerid. If the caller is a worker,
distinct from \p workerid, the caller worker automatically enters a relax
state while acquiring the target worker lock.

\fn int starpu_worker_trylock(int workerid)
\ingroup API_Workers_Properties
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
corresponding worker is not in a relax state.
If the caller is a worker, distinct from \p workerid, the caller
worker automatically enters relax state if successfully acquiring the target
worker lock.

\fn void starpu_worker_unlock(int workerid)
\ingroup API_Workers_Properties
Release the previously acquired sched mutex of \p workerid. Restore
the relax state of the caller worker if needed.

\fn void starpu_worker_lock_self(void)
\ingroup API_Workers_Properties
Acquire the current worker sched mutex.

\fn void starpu_worker_unlock_self(void)
\ingroup API_Workers_Properties
Release the current worker sched mutex.

\fn int starpu_wake_worker_relax(int workerid)
\ingroup API_Workers_Properties
Wake up \p workerid while temporarily entering the current worker relax state
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 \c 1, and \c 0 otherwise (if \p
workerid was not in the STATE_SLEEPING or in the STATE_SCHEDULING).

\fn int starpu_wake_worker_relax_light(int workerid)
\ingroup API_Workers_Properties
This is a light version of starpu_wake_worker_relax() which, when possible,
speculatively set keep_awake on the target worker without waiting for the worker
to enter the relax state.

\fn void starpu_worker_set_waking_up_callback(void (*callback)(unsigned workerid))
\ingroup API_Workers_Properties
If StarPU was compiled with blocking drivers support and worker callbacks support
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))
\ingroup API_Workers_Properties
If StarPU was compiled with blocking drivers support and worker callbacks support
enabled, allow to specify an external resource manager callback to be notified
about workers going to sleep.

\fn hwloc_cpuset_t starpu_worker_get_hwloc_cpuset(int workerid)
\ingroup API_Workers_Properties
If StarPU was compiled with \c hwloc support, return a duplicate of the
\c 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)
\ingroup API_Workers_Properties
If StarPU was compiled with \c hwloc support, return the \c hwloc object corresponding to 
the worker \p workerid.

*/