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

/* StarPU --- Runtime system for heterogeneous multicore architectures.
 *
 * Copyright (C) 2009-2021  Université de Bordeaux, CNRS (LaBRI UMR 5800), 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_Threads Threads

\brief This section describes the thread facilities provided
by StarPU. The thread function are either implemented on top of the
pthread library or the SimGrid library when the simulated performance
mode is enabled (\ref SimGridSupport).

\def STARPU_PTHREAD_CREATE_ON
\ingroup API_Threads
Call starpu_pthread_create_on() and abort on error.

\def STARPU_PTHREAD_CREATE
\ingroup API_Threads
Call starpu_pthread_create() and abort on error.

\def STARPU_PTHREAD_MUTEX_INIT
\ingroup API_Threads
Call starpu_pthread_mutex_init() and abort on error.

\def STARPU_PTHREAD_MUTEX_INIT0
\ingroup API_Threads
Call starpu_pthread_mutex_init() only if the content of
PTHREAD_MUTEX_INITIALIZER is not zero. This should be called instead
of STARPU_PTHREAD_MUTEX_INIT when it is known that the content of the
pthread_mutex_t was already zeroed.

\def STARPU_PTHREAD_MUTEX_DESTROY
\ingroup API_Threads
Call starpu_pthread_mutex_destroy() and abort on error.

\def STARPU_PTHREAD_MUTEX_LOCK
\ingroup API_Threads
Call starpu_pthread_mutex_lock() and abort on error.

\def STARPU_PTHREAD_MUTEX_UNLOCK
\ingroup API_Threads
Call starpu_pthread_mutex_unlock() and abort on error.

\def STARPU_PTHREAD_KEY_CREATE
\ingroup API_Threads
Call starpu_pthread_key_create() and abort on error.

\def STARPU_PTHREAD_KEY_DELETE
\ingroup API_Threads
Call starpu_pthread_key_delete() and abort on error.

\def STARPU_PTHREAD_SETSPECIFIC
\ingroup API_Threads
Call starpu_pthread_setspecific() and abort on error.

\def STARPU_PTHREAD_GETSPECIFIC
\ingroup API_Threads
Call starpu_pthread_getspecific() and abort on error.

\def STARPU_PTHREAD_RWLOCK_INIT
\ingroup API_Threads
Call starpu_pthread_rwlock_init() and abort on error.

\def STARPU_PTHREAD_RWLOCK_INIT0
\ingroup API_Threads
Call starpu_pthread_rwlock_init() only if the content of
PTHREAD_RWLOCK_INITIALIZER is not zero. This should be called instead
of STARPU_PTHREAD_RWLOCK_INIT when it is known that the content of the
pthread_rwlock_t was already zeroed.

\def STARPU_PTHREAD_RWLOCK_RDLOCK
\ingroup API_Threads
Call starpu_pthread_rwlock_rdlock() and abort on error.

\def STARPU_PTHREAD_RWLOCK_WRLOCK
\ingroup API_Threads
Call starpu_pthread_rwlock_wrlock() and abort on error.

\def STARPU_PTHREAD_RWLOCK_UNLOCK
\ingroup API_Threads
Call starpu_pthread_rwlock_unlock() and abort on error.

\def STARPU_PTHREAD_RWLOCK_DESTROY
\ingroup API_Threads
Call starpu_pthread_rwlock_destroy() and abort on error.

\def STARPU_PTHREAD_COND_INIT
\ingroup API_Threads
Call starpu_pthread_cond_init() and abort on error.

\def STARPU_PTHREAD_COND_INIT0
\ingroup API_Threads
Call starpu_pthread_cond_init() only if the content of
PTHREAD_COND_INITIALIZER is not zero. This should be called instead
of STARPU_PTHREAD_COND_INIT when it is known that the content of the
pthread_cond_t was already zeroed.

\def STARPU_PTHREAD_COND_DESTROY
\ingroup API_Threads
Call starpu_pthread_cond_destroy() and abort on error.

\def STARPU_PTHREAD_COND_SIGNAL
\ingroup API_Threads
Call starpu_pthread_cond_signal() and abort on error.

\def STARPU_PTHREAD_COND_BROADCAST
\ingroup API_Threads
Call starpu_pthread_cond_broadcast() and abort on error.

\def STARPU_PTHREAD_COND_WAIT
\ingroup API_Threads
Call starpu_pthread_cond_wait() and abort on error.

\def STARPU_PTHREAD_BARRIER_INIT
\ingroup API_Threads
Call starpu_pthread_barrier_init() and abort on error.

\def STARPU_PTHREAD_BARRIER_DESTROY
\ingroup API_Threads
Call starpu_pthread_barrier_destroy() and abort on error.

\def STARPU_PTHREAD_BARRIER_WAIT
\ingroup API_Threads
Call starpu_pthread_barrier_wait() and abort on error.

\fn int starpu_pthread_create_on(char *name, starpu_pthread_t *thread, const starpu_pthread_attr_t *attr, void *(*start_routine) (void *), void *arg, int where)
\ingroup API_Threads

\fn int starpu_pthread_create(starpu_pthread_t *thread, const starpu_pthread_attr_t *attr, void *(*start_routine) (void *), void *arg)
\ingroup API_Threads
Start a new thread in the calling process. The new
thread starts execution by invoking \p start_routine; \p arg is passed
as the sole argument of \p start_routine.

\fn int starpu_pthread_join(starpu_pthread_t thread, void **retval)
\ingroup API_Threads
Wait for the thread specified by \p thread to
terminate.  If that thread has already terminated, then the function
returns immediately. The thread specified by \p thread must be
joinable.

\fn int starpu_pthread_exit(void *retval)
\ingroup API_Threads
Terminate the calling thread and return a value via
\p retval that (if the thread is joinable) is available to another thread
in the same process that calls starpu_pthread_join().

\fn int starpu_pthread_attr_init(starpu_pthread_attr_t *attr)
\ingroup API_Threads
Initialize the thread attributes object pointed to by
\p attr with default attribute values.

Do not do anything when the simulated performance mode is enabled
(\ref SimGridSupport).

\fn int starpu_pthread_attr_destroy(starpu_pthread_attr_t *attr)
\ingroup API_Threads
Destroy a thread attributes object which is no longer
required. Destroying a thread attributes object has no effect on
threads that were created using that object.

Do not do anything when the simulated performance mode is enabled
(\ref SimGridSupport).

\fn int starpu_pthread_attr_setdetachstate(starpu_pthread_attr_t *attr, int detachstate)
\ingroup API_Threads
Set the detach state attribute of the thread attributes
object referred to by \p attr to the value specified in \p
detachstate.  The detach state attribute determines whether a thread
created using the thread attributes object \p attr will be created in
a joinable or a detached state.

Do not do anything when the simulated performance mode is enabled
(\ref SimGridSupport).

\fn int starpu_pthread_mutex_init(starpu_pthread_mutex_t *mutex, const starpu_pthread_mutexattr_t *mutexattr)
\ingroup API_Threads
Initialize the mutex object pointed to by \p mutex
according to the mutex attributes specified in \p mutexattr.  If \p
mutexattr is <c>NULL</c>, default attributes are used instead.

\fn int starpu_pthread_mutex_destroy(starpu_pthread_mutex_t *mutex)
\ingroup API_Threads
Destroy a mutex object, and free the resources it might
hold. The mutex must be unlocked on entrance.

\fn int starpu_pthread_mutex_lock(starpu_pthread_mutex_t *mutex)
\ingroup API_Threads
Lock the given \p mutex. If \p mutex is currently
unlocked, it becomes locked and owned by the calling thread, and the
function returns immediately. If \p mutex is already locked by
another thread, the function suspends the calling thread until
\p mutex is unlocked.

This function also produces trace when the configure option
\ref enable-fxt-lock "--enable-fxt-lock" is enabled.

\fn int starpu_pthread_mutex_unlock(starpu_pthread_mutex_t *mutex)
\ingroup API_Threads
Unlock the given \p mutex. The mutex is assumed to be
locked and owned by the calling thread on entrance to
starpu_pthread_mutex_unlock().

This function also produces trace when the configure option
\ref enable-fxt-lock "--enable-fxt-lock" is enabled.

\fn int starpu_pthread_mutex_trylock(starpu_pthread_mutex_t *mutex)
\ingroup API_Threads
Behave identically to starpu_pthread_mutex_lock(),
except that it does not block the calling thread if the mutex is
already locked by another thread (or by the calling thread in the case
of a ``fast''  mutex). Instead, the function returns immediately with
the error code \c EBUSY.

This function also produces trace when the configure option
\ref enable-fxt-lock "--enable-fxt-lock" is enabled.

\typedef STARPU_PTHREAD_MUTEX_INITIALIZER
\ingroup API_Threads
Initialize the mutex given in parameter.

\fn int starpu_pthread_mutexattr_gettype(const starpu_pthread_mutexattr_t *attr, int *type)
\ingroup API_Threads
todo

\fn int starpu_pthread_mutexattr_settype(starpu_pthread_mutexattr_t *attr, int type)
\ingroup API_Threads
todo

\fn int starpu_pthread_mutexattr_destroy(starpu_pthread_mutexattr_t *attr)
\ingroup API_Threads
todo

\fn int starpu_pthread_mutexattr_init(starpu_pthread_mutexattr_t *attr)
\ingroup API_Threads
todo

\fn int starpu_pthread_key_create(starpu_pthread_key_t *key, void (*destr_function) (void *))
\ingroup API_Threads
Allocate a new TSD key. The key is stored in the
location pointed to by \p key.

\fn int starpu_pthread_key_delete(starpu_pthread_key_t key)
\ingroup API_Threads
Deallocate a TSD key. Do not check whether
non-<c>NULL</c> values are associated with that key in the currently
executing threads, nor call the destructor function associated with
the key.

\fn int starpu_pthread_setspecific(starpu_pthread_key_t key, const void *pointer)
\ingroup API_Threads
Change the value associated with \p key in the calling
thread, storing the given \p pointer instead.

\fn void *starpu_pthread_getspecific(starpu_pthread_key_t key)
\ingroup API_Threads
Return the value associated with \p key on success, and
<c>NULL</c> on error.

\typedef STARPU_PTHREAD_COND_INITIALIZER
\ingroup API_Threads
Initialize the condition variable given in parameter.

\fn int starpu_pthread_cond_init(starpu_pthread_cond_t *cond, starpu_pthread_condattr_t *cond_attr)
\ingroup API_Threads
Initialize the condition variable \p cond, using the
condition attributes specified in \p cond_attr, or default attributes
if \p cond_attr is <c>NULL</c>.

\fn int starpu_pthread_cond_signal(starpu_pthread_cond_t *cond)
\ingroup API_Threads
Restart one of the threads that are waiting on the
condition variable \p cond. If no threads are waiting on \p cond,
nothing happens. If several threads are waiting on \p cond, exactly
one is restarted, but it is not specified which.

\fn int starpu_pthread_cond_broadcast(starpu_pthread_cond_t *cond)
\ingroup API_Threads
Restart all the threads that are waiting on the
condition variable \p cond. Nothing happens if no threads are waiting on \p cond.

\fn int starpu_pthread_cond_wait(starpu_pthread_cond_t *cond, starpu_pthread_mutex_t *mutex)
\ingroup API_Threads
Atomically unlock \p mutex (as per
starpu_pthread_mutex_unlock()) and wait for the condition variable \p cond
to be signaled. The thread execution is suspended and does not consume
any CPU time until the condition variable is signaled. The mutex must
be locked by the calling thread on entrance to
starpu_pthread_cond_wait(). Before returning to the calling thread, the
function re-acquires mutex (as per starpu_pthread_mutex_lock()).

This function also produces trace when the configure option
\ref enable-fxt-lock "--enable-fxt-lock" is enabled.

\fn int starpu_pthread_cond_timedwait(starpu_pthread_cond_t *cond, starpu_pthread_mutex_t *mutex, const struct timespec *abstime)
\ingroup API_Threads
Atomicall unlocks \p mutex and wait on \p cond, as
starpu_pthread_cond_wait() does, but also bound the duration of
the wait with \p abstime.

\fn int starpu_pthread_cond_destroy(starpu_pthread_cond_t *cond)
\ingroup API_Threads
Destroy a condition variable, freeing the resources it
might hold. No threads must be waiting on the condition variable on
entrance to the function.

\fn int starpu_pthread_rwlock_init(starpu_pthread_rwlock_t *rwlock, const starpu_pthread_rwlockattr_t *attr)
\ingroup API_Threads
Similar to starpu_pthread_mutex_init().

\fn int starpu_pthread_rwlock_destroy(starpu_pthread_rwlock_t *rwlock)
\ingroup API_Threads
Similar to starpu_pthread_mutex_destroy().

\fn int starpu_pthread_rwlock_rdlock(starpu_pthread_rwlock_t *rwlock)
\ingroup API_Threads
Similar to starpu_pthread_mutex_lock().

\fn int starpu_pthread_rwlock_tryrdlock(starpu_pthread_rwlock_t *rwlock)
\ingroup API_Threads
todo

\fn int starpu_pthread_rwlock_wrlock(starpu_pthread_rwlock_t *rwlock)
\ingroup API_Threads
Similar to starpu_pthread_mutex_lock().

\fn int starpu_pthread_rwlock_trywrlock(starpu_pthread_rwlock_t *rwlock)
\ingroup API_Threads
todo

\fn int starpu_pthread_rwlock_unlock(starpu_pthread_rwlock_t *rwlock)
\ingroup API_Threads
Similar to starpu_pthread_mutex_unlock().

\fn int starpu_pthread_barrier_init(starpu_pthread_barrier_t *barrier, const starpu_pthread_barrierattr_t *attr, unsigned count)
\ingroup API_Threads
todo

\fn int starpu_pthread_barrier_destroy(starpu_pthread_barrier_t *barrier)
\ingroup API_Threads
todo

\fn int starpu_pthread_barrier_wait(starpu_pthread_barrier_t *barrier)
\ingroup API_Threads
todo

\fn int starpu_pthread_spin_init(starpu_pthread_spinlock_t *lock, int pshared)
\ingroup API_Threads
todo

\fn int starpu_pthread_spin_destroy(starpu_pthread_spinlock_t *lock)
\ingroup API_Threads
todo

\fn int starpu_pthread_spin_lock(starpu_pthread_spinlock_t *lock)
\ingroup API_Threads
todo

\fn int starpu_pthread_spin_trylock(starpu_pthread_spinlock_t *lock)
\ingroup API_Threads
todo

\fn int starpu_pthread_spin_unlock(starpu_pthread_spinlock_t *lock)
\ingroup API_Threads
todo

\fn void starpu_sleep(float nb_sec)
\ingroup API_Threads
Similar to calling Unix' \c sleep function, except that it takes a float
to allow sub-second sleeping, and when StarPU is compiled in SimGrid mode it
does not really sleep but just makes SimGrid record that the thread has taken
some time to sleep.

*/