doc: threads documentation

doc/doxygen/Makefile.am

@@ -93,7 +93,8 @@ chapters =	\
 	chapters/api/task_lists.doxy \
 	chapters/api/top.doxy \
 	chapters/api/versioning.doxy \
-	chapters/api/workers.doxy
+	chapters/api/workers.doxy \
+	chapters/api/threads.doxy
 
 starpu_config.h: $(top_srcdir)/include/starpu_config.h.in
 	sed 's/#undef \(.*\)/#define \1 1/' $< > $@

doc/doxygen/chapters/api/threads.doxy

@@ -0,0 +1,306 @@
+/*
+ * 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 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 SimulatedPerformance).
+
+\def STARPU_PTHREAD_CREATE_ON
+\ingroup API_Threads
+This macro calls the function starpu_pthread_create_on() and aborts on error.
+
+\def STARPU_PTHREAD_CREATE
+\ingroup API_Threads
+This macro calls the function starpu_pthread_create() and aborts on error.
+
+\def STARPU_PTHREAD_MUTEX_INIT
+\ingroup API_Threads
+This macro calls the function starpu_pthread_mutex_init() and aborts
+on error.
+
+\def STARPU_PTHREAD_MUTEX_DESTROY
+\ingroup API_Threads
+This macro calls the function starpu_pthread_mutex_destroy() and
+aborts on error.
+
+\def STARPU_PTHREAD_MUTEX_LOCK
+\ingroup API_Threads
+This macro calls the function starpu_pthread_mutex_lock() and aborts
+on error.
+
+\def STARPU_PTHREAD_MUTEX_UNLOCK
+\ingroup API_Threads
+This macro calls the function starpu_pthread_mutex_unlock() and aborts
+on error.
+
+\def STARPU_PTHREAD_KEY_CREATE
+\ingroup API_Threads
+This macro calls the function starpu_pthread_key_create() and aborts
+on error.
+
+\def STARPU_PTHREAD_KEY_DELETE
+\ingroup API_Threads
+This macro calls the function starpu_pthread_key_delete() and aborts
+on error.
+
+\def STARPU_PTHREAD_SETSPECIFIC
+\ingroup API_Threads
+This macro calls the function starpu_pthread_setspecific() and aborts
+on error.
+
+\def STARPU_PTHREAD_GETSPECIFIC
+\ingroup API_Threads
+This macro calls the function starpu_pthread_getspecific() and aborts
+on error.
+
+\def STARPU_PTHREAD_RWLOCK_INIT
+\ingroup API_Threads
+This macro calls the function starpu_pthread_rwlock_init() and aborts
+on error.
+
+\def STARPU_PTHREAD_RWLOCK_RDLOCK
+\ingroup API_Threads
+This macro calls the function starpu_pthread_rwlock_rdlock() and
+aborts on error.
+
+\def STARPU_PTHREAD_RWLOCK_WRLOCK
+\ingroup API_Threads
+This macro calls the function starpu_pthread_rwlock_wrlock() and
+aborts on error.
+
+\def STARPU_PTHREAD_RWLOCK_UNLOCK
+\ingroup API_Threads
+This macro calls the function starpu_pthread_rwlock_unlock() and
+aborts on error.
+
+\def STARPU_PTHREAD_RWLOCK_DESTROY
+\ingroup API_Threads
+This macro calls the function starpu_pthread_rwlock_destroy() and
+aborts on error.
+
+\def STARPU_PTHREAD_COND_INIT
+\ingroup API_Threads
+This macro calls the function starpu_pthread_cond_init() and aborts on error.
+
+\def STARPU_PTHREAD_COND_DESTROY
+\ingroup API_Threads
+This macro calls the function starpu_pthread_cond_destroy() and aborts
+on error.
+
+\def STARPU_PTHREAD_COND_SIGNAL
+\ingroup API_Threads
+This macro calls the function starpu_pthread_cond_signal() and aborts
+on error.
+
+\def STARPU_PTHREAD_COND_BROADCAST
+\ingroup API_Threads
+This macro calls the function starpu_pthread_cond_broadcast() and
+aborts on error.
+
+\def STARPU_PTHREAD_COND_WAIT
+\ingroup API_Threads
+This macro calls the function starpu_pthread_cond_wait() and aborts on error.
+
+\def STARPU_PTHREAD_BARRIER_INIT
+\ingroup API_Threads
+This macro calls the function starpu_pthread_barrier_init() and aborts
+on error.
+
+\def STARPU_PTHREAD_BARRIER_DESTROY
+\ingroup API_Threads
+This macro calls the function starpu_pthread_barrier_destroy() and
+aborts on error.
+
+\def STARPU_PTHREAD_BARRIER_WAIT
+\ingroup API_Threads
+This macro calls the function starpu_pthread_barrier_wait() and aborts
+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
+This function starts 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
+This function waits 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_attr_init(starpu_pthread_attr_t *attr)
+\ingroup API_Threads
+This function initializes the thread attributes object pointed to by
+\p attr with default attribute values.
+
+It does not do anything when the simulated performance mode is enabled
+(\ref SimulatedPerformance).
+
+\fn int starpu_pthread_attr_destroy(starpu_pthread_attr_t *attr)
+\ingroup API_Threads
+This function destroys 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.
+
+It does not do anything when the simulated performance mode is enabled
+(\ref SimulatedPerformance).
+
+\fn int starpu_pthread_attr_setdetachstate(starpu_pthread_attr_t *attr, int detachstate)
+\ingroup API_Threads
+This function sets 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.
+
+It does not do anything when the simulated performance mode is enabled
+(\ref SimulatedPerformance).
+
+\fn int starpu_pthread_mutex_init(starpu_pthread_mutex_t *mutex, const starpu_pthread_mutexattr_t *mutexattr)
+\ingroup API_Threads
+This function initializes the mutex object pointed to by \p mutex
+according to the mutex attributes specified in \p mutexattr.  If \p
+mutexattr is NULL, default attributes are used instead.
+
+\fn int starpu_pthread_mutex_destroy(starpu_pthread_mutex_t *mutex)
+\ingroup API_Threads
+This function destroys a mutex object, freeing 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
+This function locks the given mutex. If the mutex is currently
+unlocked, it becomes locked and owned by the calling thread, and the
+function returns immediately. If the mutex is already locked by
+another thread, the function suspends the calling thread until the
+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
+This function unlocks the given 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
+This function behaves 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 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
+This macro initializes the mutex given in parameter.
+
+\fn int starpu_pthread_key_create(starpu_pthread_key_t *key, void (*destr_function) (void *))
+\ingroup API_Threads
+This function allocates 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
+This function deallocates a TSD key. It does not check whether
+non-NULL 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
+This function changes the value associated with \p key in the calling
+thread, storing the given \p pointer instead.
+
+\fn  *starpu_pthread_getspecific(starpu_pthread_key_t key)
+\ingroup API_Threads
+This function returns the value associated with \p key on success, and
+NULL on error.
+
+\typedef STARPU_PTHREAD_COND_INITIALIZER
+\ingroup API_Threads
+This macro initializes the condition variable given in parameter.
+
+\fn starpu_pthread_cond_init(starpu_pthread_cond_t *cond, starpu_pthread_condattr_t *cond_attr)
+\ingroup API_Threads
+This function initializes the condition variable \p cond, using the
+condition attributes specified in \p cond_attr, or default attributes
+if \p cond_attr is NULL.
+
+\fn starpu_pthread_cond_signal(starpu_pthread_cond_t *cond)
+\ingroup API_Threads
+This function restarts 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 not specified which.
+
+\fn starpu_pthread_cond_broadcast(starpu_pthread_cond_t *cond)
+\ingroup API_Threads
+This function restarts all the threads that are waiting on the
+condition variable \p cond. Nothing happens if no threads are waiting on cond.
+
+\fn starpu_pthread_cond_wait(starpu_pthread_cond_t *cond, starpu_pthread_mutex_t *mutex)
+\ingroup API_Threads
+This function atomically unlocks the mutex (as per
+starpu_pthread_mutex_unlock()) and waits 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 starpu_pthread_cond_timedwait(starpu_pthread_cond_t *cond, starpu_pthread_mutex_t *mutex, const struct timespec *abstime)
+\ingroup API_Threads
+This function atomically unlocks \p mutex and waits on \p cond, as
+starpu_pthread_cond_wait() does, but it also bounds the duration of
+the wait.
+
+\fn starpu_pthread_cond_destroy(starpu_pthread_cond_t *cond)
+\ingroup API_Threads
+This function destroys a condition variable, freeing the resources it
+might hold. No threads must be waiting on the condition variable on
+entrance to the function.
+
+\fn starpu_pthread_rwlock_init(starpu_pthread_rwlock_t *rwlock, const starpu_pthread_rwlockattr_t *attr)
+\ingroup API_Threads
+This function is the same as starpu_pthread_mutex_init().
+
+\fn starpu_pthread_rwlock_destroy(starpu_pthread_rwlock_t *rwlock)
+\ingroup API_Threads
+This function is the same as starpu_pthread_mutex_destroy().
+
+\fn starpu_pthread_rwlock_rdlock(starpu_pthread_rwlock_t *rwlock)
+\ingroup API_Threads
+This function is the same as starpu_pthread_mutex_lock().
+
+\fn starpu_pthread_rwlock_wrlock(starpu_pthread_rwlock_t *rwlock)
+\ingroup API_Threads
+This function is the same as starpu_pthread_mutex_lock().
+
+\fn starpu_pthread_rwlock_unlock(starpu_pthread_rwlock_t *rwlock)
+\ingroup API_Threads
+This function is the same as starpu_pthread_mutex_unlock().
+
+*/

doc/doxygen/doxygen.cfg

@@ -1622,6 +1622,7 @@ PREDEFINED             = STARPU_USE_OPENCL=1 \
 			 STARPU_USE_MPI=1 \
 			 STARPU_HAVE_HWLOC=1 \
 			 STARPU_USE_SC_HYPERVISOR=1 \
+			 STARPU_SIMGRID=1 \
                          __GCC__
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then

doc/doxygen/refman.tex

@@ -193,6 +193,7 @@ Documentation License”.
 \input{group__API__Versioning}
 \input{group__API__Initialization__and__Termination}
 \input{group__API__Standard__Memory__Library}
+\input{group__API__Threads}
 \input{group__API__Workers__Properties}
 \input{group__API__Data__Management}
 \input{group__API__Data__Interfaces}