StarPU Handbook

Macros | Functions
Threads

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 (SimGrid Support). More...

## Macros
#define | STARPU_PTHREAD_CREATE_ON(name, thread, attr, routine, arg, where)
#define | STARPU_PTHREAD_CREATE(thread, attr, routine, arg)
#define | STARPU_PTHREAD_MUTEX_INIT(mutex, attr)
#define | STARPU_PTHREAD_MUTEX_DESTROY(mutex)
#define | STARPU_PTHREAD_MUTEX_LOCK(mutex)
#define | STARPU_PTHREAD_MUTEX_UNLOCK(mutex)
#define | STARPU_PTHREAD_KEY_CREATE(key, destr)
#define | STARPU_PTHREAD_KEY_DELETE(key)
#define | STARPU_PTHREAD_SETSPECIFIC(key, ptr)
#define | STARPU_PTHREAD_GETSPECIFIC(key)
#define | STARPU_PTHREAD_RWLOCK_INIT(rwlock, attr)
#define | STARPU_PTHREAD_RWLOCK_RDLOCK(rwlock)
#define | STARPU_PTHREAD_RWLOCK_WRLOCK(rwlock)
#define | STARPU_PTHREAD_RWLOCK_UNLOCK(rwlock)
#define | STARPU_PTHREAD_RWLOCK_DESTROY(rwlock)
#define | STARPU_PTHREAD_COND_INIT(cond, attr)
#define | STARPU_PTHREAD_COND_DESTROY(cond)
#define | STARPU_PTHREAD_COND_SIGNAL(cond)
#define | STARPU_PTHREAD_COND_BROADCAST(cond)
#define | STARPU_PTHREAD_COND_WAIT(cond, mutex)
#define | STARPU_PTHREAD_BARRIER_INIT(barrier, attr, count)
#define | STARPU_PTHREAD_BARRIER_DESTROY(barrier)
#define | STARPU_PTHREAD_BARRIER_WAIT(barrier)
#define | STARPU_PTHREAD_MUTEX_INITIALIZER
#define | STARPU_PTHREAD_COND_INITIALIZER

## Functions
int | starpu_pthread_create (starpu_pthread_t *thread, const starpu_pthread_attr_t *attr, void *(*start_routine)(void *), void *arg)
int | starpu_pthread_join (starpu_pthread_t thread, void **retval)
int | starpu_pthread_exit (void *retval) STARPU_ATTRIBUTE_NORETURN
int | starpu_pthread_attr_init (starpu_pthread_attr_t *attr)
int | starpu_pthread_attr_destroy (starpu_pthread_attr_t *attr)
int | starpu_pthread_attr_setdetachstate (starpu_pthread_attr_t *attr, int detachstate)
int | starpu_pthread_mutex_init (starpu_pthread_mutex_t *mutex, const starpu_pthread_mutexattr_t *mutexattr)
int | starpu_pthread_mutex_destroy (starpu_pthread_mutex_t *mutex)
int | starpu_pthread_mutex_lock (starpu_pthread_mutex_t *mutex)
int | starpu_pthread_mutex_unlock (starpu_pthread_mutex_t *mutex)
int | starpu_pthread_mutex_trylock (starpu_pthread_mutex_t *mutex)
int | starpu_pthread_mutexattr_gettype (const starpu_pthread_mutexattr_t *attr, int *type)
int | starpu_pthread_mutexattr_settype (starpu_pthread_mutexattr_t *attr, int type)
int | starpu_pthread_mutexattr_destroy (starpu_pthread_mutexattr_t *attr)
int | starpu_pthread_mutexattr_init (starpu_pthread_mutexattr_t *attr)
int | starpu_pthread_key_create (starpu_pthread_key_t *key, void(*destr_function)(void *))
int | starpu_pthread_key_delete (starpu_pthread_key_t key)
int | starpu_pthread_setspecific (starpu_pthread_key_t key, const void *pointer)
void * | starpu_pthread_getspecific (starpu_pthread_key_t key)
int | starpu_pthread_cond_init (starpu_pthread_cond_t *cond, starpu_pthread_condattr_t *cond_attr)
int | starpu_pthread_cond_signal (starpu_pthread_cond_t *cond)
int | starpu_pthread_cond_broadcast (starpu_pthread_cond_t *cond)
int | starpu_pthread_cond_wait (starpu_pthread_cond_t *cond, starpu_pthread_mutex_t *mutex)
int | starpu_pthread_cond_timedwait (starpu_pthread_cond_t *cond, starpu_pthread_mutex_t *mutex, const struct timespec *abstime)
int | starpu_pthread_cond_destroy (starpu_pthread_cond_t *cond)
int | starpu_pthread_rwlock_init (starpu_pthread_rwlock_t *rwlock, const starpu_pthread_rwlockattr_t *attr)
int | starpu_pthread_rwlock_destroy (starpu_pthread_rwlock_t *rwlock)
int | starpu_pthread_rwlock_rdlock (starpu_pthread_rwlock_t *rwlock)
int | starpu_pthread_rwlock_tryrdlock (starpu_pthread_rwlock_t *rwlock)
int | starpu_pthread_rwlock_wrlock (starpu_pthread_rwlock_t *rwlock)
int | starpu_pthread_rwlock_trywrlock (starpu_pthread_rwlock_t *rwlock)
int | starpu_pthread_rwlock_unlock (starpu_pthread_rwlock_t *rwlock)
int | starpu_pthread_barrier_init (starpu_pthread_barrier_t *barrier, const starpu_pthread_barrierattr_t *attr, unsigned count)
int | starpu_pthread_barrier_destroy (starpu_pthread_barrier_t *barrier)
int | starpu_pthread_barrier_wait (starpu_pthread_barrier_t *barrier)
int | starpu_pthread_spin_init (starpu_pthread_spinlock_t *lock, int pshared)
int | starpu_pthread_spin_destroy (starpu_pthread_spinlock_t *lock)
int | starpu_pthread_spin_lock (starpu_pthread_spinlock_t *lock)
int | starpu_pthread_spin_trylock (starpu_pthread_spinlock_t *lock)
int | starpu_pthread_spin_unlock (starpu_pthread_spinlock_t *lock)
void | starpu_sleep (float nb_sec)

## Detailed Description

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 (SimGrid Support).

## Macro Definition Documentation

## ◆ STARPU_PTHREAD_CREATE_ON

#define STARPU_PTHREAD_CREATE_ON | ( |  | name,
|  |  | thread,
|  |  | attr,
|  |  | routine,
|  |  | arg,
|  |  | where
| ) |  |

Call starpu_pthread_create_on() and abort on error.

## ◆ STARPU_PTHREAD_CREATE

#define STARPU_PTHREAD_CREATE | ( |  | thread,
|  |  | attr,
|  |  | routine,
|  |  | arg
| ) |  |

Call starpu_pthread_create() and abort on error.

## ◆ STARPU_PTHREAD_MUTEX_INIT

#define STARPU_PTHREAD_MUTEX_INIT | ( |  | mutex,
|  |  | attr
| ) |  |

Call starpu_pthread_mutex_init() and abort on error.

## ◆ STARPU_PTHREAD_MUTEX_DESTROY

#define STARPU_PTHREAD_MUTEX_DESTROY | ( |  | mutex | ) |

Call starpu_pthread_mutex_destroy() and abort on error.

## ◆ STARPU_PTHREAD_MUTEX_LOCK

#define STARPU_PTHREAD_MUTEX_LOCK | ( |  | mutex | ) |

Call starpu_pthread_mutex_lock() and abort on error.

## ◆ STARPU_PTHREAD_MUTEX_UNLOCK

#define STARPU_PTHREAD_MUTEX_UNLOCK | ( |  | mutex | ) |

Call starpu_pthread_mutex_unlock() and abort on error.

## ◆ STARPU_PTHREAD_KEY_CREATE

#define STARPU_PTHREAD_KEY_CREATE | ( |  | key,
|  |  | destr
| ) |  |

Call starpu_pthread_key_create() and abort on error.

## ◆ STARPU_PTHREAD_KEY_DELETE

#define STARPU_PTHREAD_KEY_DELETE | ( |  | key | ) |

Call starpu_pthread_key_delete() and abort on error.

## ◆ STARPU_PTHREAD_SETSPECIFIC

#define STARPU_PTHREAD_SETSPECIFIC | ( |  | key,
|  |  | ptr
| ) |  |

Call starpu_pthread_setspecific() and abort on error.

## ◆ STARPU_PTHREAD_GETSPECIFIC

#define STARPU_PTHREAD_GETSPECIFIC | ( |  | key | ) |

Call starpu_pthread_getspecific() and abort on error.

## ◆ STARPU_PTHREAD_RWLOCK_INIT

#define STARPU_PTHREAD_RWLOCK_INIT | ( |  | rwlock,
|  |  | attr
| ) |  |

Call starpu_pthread_rwlock_init() and abort on error.

## ◆ STARPU_PTHREAD_RWLOCK_RDLOCK

#define STARPU_PTHREAD_RWLOCK_RDLOCK | ( |  | rwlock | ) |

Call starpu_pthread_rwlock_rdlock() and abort on error.

## ◆ STARPU_PTHREAD_RWLOCK_WRLOCK

#define STARPU_PTHREAD_RWLOCK_WRLOCK | ( |  | rwlock | ) |

Call starpu_pthread_rwlock_wrlock() and abort on error.

## ◆ STARPU_PTHREAD_RWLOCK_UNLOCK

#define STARPU_PTHREAD_RWLOCK_UNLOCK | ( |  | rwlock | ) |

Call starpu_pthread_rwlock_unlock() and abort on error.

## ◆ STARPU_PTHREAD_RWLOCK_DESTROY

#define STARPU_PTHREAD_RWLOCK_DESTROY | ( |  | rwlock | ) |

Call starpu_pthread_rwlock_destroy() and abort on error.

## ◆ STARPU_PTHREAD_COND_INIT

#define STARPU_PTHREAD_COND_INIT | ( |  | cond,
|  |  | attr
| ) |  |

Call starpu_pthread_cond_init() and abort on error.

## ◆ STARPU_PTHREAD_COND_DESTROY

#define STARPU_PTHREAD_COND_DESTROY | ( |  | cond | ) |

Call starpu_pthread_cond_destroy() and abort on error.

## ◆ STARPU_PTHREAD_COND_SIGNAL

#define STARPU_PTHREAD_COND_SIGNAL | ( |  | cond | ) |

Call starpu_pthread_cond_signal() and abort on error.

## ◆ STARPU_PTHREAD_COND_BROADCAST

#define STARPU_PTHREAD_COND_BROADCAST | ( |  | cond | ) |

Call starpu_pthread_cond_broadcast() and abort on error.

## ◆ STARPU_PTHREAD_COND_WAIT

#define STARPU_PTHREAD_COND_WAIT | ( |  | cond,
|  |  | mutex
| ) |  |

Call starpu_pthread_cond_wait() and abort on error.

## ◆ STARPU_PTHREAD_BARRIER_INIT

#define STARPU_PTHREAD_BARRIER_INIT | ( |  | barrier,
|  |  | attr,
|  |  | count
| ) |  |

Call starpu_pthread_barrier_init() and abort on error.

## ◆ STARPU_PTHREAD_BARRIER_DESTROY

#define STARPU_PTHREAD_BARRIER_DESTROY | ( |  | barrier | ) |

Call starpu_pthread_barrier_destroy() and abort on error.

## ◆ STARPU_PTHREAD_BARRIER_WAIT

#define STARPU_PTHREAD_BARRIER_WAIT | ( |  | barrier | ) |

Call starpu_pthread_barrier_wait() and abort on error.

## ◆ STARPU_PTHREAD_MUTEX_INITIALIZER

STARPU_PTHREAD_MUTEX_INITIALIZER

Initialize the mutex given in parameter.

## ◆ STARPU_PTHREAD_COND_INITIALIZER

STARPU_PTHREAD_COND_INITIALIZER

Initialize the condition variable given in parameter.

## Function Documentation

## ◆ starpu_pthread_create()

int starpu_pthread_create | ( | starpu_pthread_t * | thread,
|  | const starpu_pthread_attr_t * | attr,
|  | void *(*)(void *) | start_routine,
|  | void * | arg
| ) |  |

Start a new thread in the calling process. The new thread starts execution by invoking `start_routine`; `arg` is passed as the sole argument of `start_routine`.

## ◆ starpu_pthread_join()

int starpu_pthread_join | ( | starpu_pthread_t | thread,
|  | void ** | retval
| ) |  |

Wait for the thread specified by `thread` to terminate. If that thread has already terminated, then the function returns immediately. The thread specified by `thread` must be joinable.

## ◆ starpu_pthread_exit()

int starpu_pthread_exit | ( | void * | retval | ) |

Terminate the calling thread and return a value via `retval` that (if the thread is joinable) is available to another thread in the same process that calls starpu_pthread_join().

## ◆ starpu_pthread_attr_init()

int starpu_pthread_attr_init | ( | starpu_pthread_attr_t * | attr | ) |

Initialize the thread attributes object pointed to by `attr` with default attribute values.

Do not do anything when the simulated performance mode is enabled (SimGrid Support).

## ◆ starpu_pthread_attr_destroy()

int starpu_pthread_attr_destroy | ( | starpu_pthread_attr_t * | attr | ) |

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 (SimGrid Support).

## ◆ starpu_pthread_attr_setdetachstate()

int starpu_pthread_attr_setdetachstate | ( | starpu_pthread_attr_t * | attr,
|  | int | detachstate
| ) |  |

Set the detach state attribute of the thread attributes object referred to by `attr` to the value specified in `detachstate`. The detach state attribute determines whether a thread created using the thread attributes object `attr` will be created in a joinable or a detached state.

Do not do anything when the simulated performance mode is enabled (SimGrid Support).

## ◆ starpu_pthread_mutex_init()

int starpu_pthread_mutex_init | ( | starpu_pthread_mutex_t * | mutex,
|  | const starpu_pthread_mutexattr_t * | mutexattr
| ) |  |

Initialize the mutex object pointed to by `mutex` according to the mutex attributes specified in `mutexattr`. If `mutexattr` is `NULL`, default attributes are used instead.

## ◆ starpu_pthread_mutex_destroy()

int starpu_pthread_mutex_destroy | ( | starpu_pthread_mutex_t * | mutex | ) |

Destroy a mutex object, and free the resources it might hold. The mutex must be unlocked on entrance.

## ◆ starpu_pthread_mutex_lock()

int starpu_pthread_mutex_lock | ( | starpu_pthread_mutex_t * | mutex | ) |

Lock the given `mutex`. If `mutex` is currently unlocked, it becomes locked and owned by the calling thread, and the function returns immediately. If `mutex` is already locked by another thread, the function suspends the calling thread until `mutex` is unlocked.

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

## ◆ starpu_pthread_mutex_unlock()

int starpu_pthread_mutex_unlock | ( | starpu_pthread_mutex_t * | mutex | ) |

Unlock 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 --enable-fxt-lock is enabled.

## ◆ starpu_pthread_mutex_trylock()

int starpu_pthread_mutex_trylock | ( | starpu_pthread_mutex_t * | mutex | ) |

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 `EBUSY`.

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

## ◆ starpu_pthread_mutexattr_gettype()

int starpu_pthread_mutexattr_gettype | ( | const starpu_pthread_mutexattr_t * | attr,
|  | int * | type
| ) |  |

todo

## ◆ starpu_pthread_mutexattr_settype()

int starpu_pthread_mutexattr_settype | ( | starpu_pthread_mutexattr_t * | attr,
|  | int | type
| ) |  |

todo

## ◆ starpu_pthread_mutexattr_destroy()

int starpu_pthread_mutexattr_destroy | ( | starpu_pthread_mutexattr_t * | attr | ) |

todo

## ◆ starpu_pthread_mutexattr_init()

int starpu_pthread_mutexattr_init | ( | starpu_pthread_mutexattr_t * | attr | ) |

todo

## ◆ starpu_pthread_key_create()

int starpu_pthread_key_create | ( | starpu_pthread_key_t * | key,
|  | void(*)(void *) | destr_function
| ) |  |

Allocate a new TSD key. The key is stored in the location pointed to by `key`.

## ◆ starpu_pthread_key_delete()

int starpu_pthread_key_delete | ( | starpu_pthread_key_t | key | ) |

Deallocate a TSD key. Do 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.

## ◆ starpu_pthread_setspecific()

int starpu_pthread_setspecific | ( | starpu_pthread_key_t | key,
|  | const void * | pointer
| ) |  |

Change the value associated with `key` in the calling thread, storing the given `pointer` instead.

## ◆ starpu_pthread_getspecific()

void * starpu_pthread_getspecific | ( | starpu_pthread_key_t | key | ) |

Return the value associated with `key` on success, and `NULL` on error.

## ◆ starpu_pthread_cond_init()

int starpu_pthread_cond_init | ( | starpu_pthread_cond_t * | cond,
|  | starpu_pthread_condattr_t * | cond_attr
| ) |  |

Initialize the condition variable `cond`, using the condition attributes specified in `cond_attr`, or default attributes if `cond_attr` is `NULL`.

## ◆ starpu_pthread_cond_signal()

int starpu_pthread_cond_signal | ( | starpu_pthread_cond_t * | cond | ) |

Restart one of the threads that are waiting on the condition variable `cond`. If no threads are waiting on `cond`, nothing happens. If several threads are waiting on `cond`, exactly one is restarted, but it is not specified which.

## ◆ starpu_pthread_cond_broadcast()

int starpu_pthread_cond_broadcast | ( | starpu_pthread_cond_t * | cond | ) |

Restart all the threads that are waiting on the condition variable `cond`. Nothing happens if no threads are waiting on `cond`.

## ◆ starpu_pthread_cond_wait()

int starpu_pthread_cond_wait | ( | starpu_pthread_cond_t * | cond,
|  | starpu_pthread_mutex_t * | mutex
| ) |  |

Atomically unlock `mutex` (as per starpu_pthread_mutex_unlock()) and wait for the condition variable `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 --enable-fxt-lock is enabled.

## ◆ starpu_pthread_cond_timedwait()

int starpu_pthread_cond_timedwait | ( | starpu_pthread_cond_t * | cond,
|  | starpu_pthread_mutex_t * | mutex,
|  | const struct timespec * | abstime
| ) |  |

Atomicall unlocks `mutex` and wait on `cond`, as starpu_pthread_cond_wait() does, but also bound the duration of the wait with `abstime`.

## ◆ starpu_pthread_cond_destroy()

int starpu_pthread_cond_destroy | ( | starpu_pthread_cond_t * | cond | ) |

Destroy a condition variable, freeing the resources it might hold. No threads must be waiting on the condition variable on entrance to the function.

## ◆ starpu_pthread_rwlock_init()

int starpu_pthread_rwlock_init | ( | starpu_pthread_rwlock_t * | rwlock,
|  | const starpu_pthread_rwlockattr_t * | attr
| ) |  |

Similar to starpu_pthread_mutex_init().

## ◆ starpu_pthread_rwlock_destroy()

int starpu_pthread_rwlock_destroy | ( | starpu_pthread_rwlock_t * | rwlock | ) |

Similar to starpu_pthread_mutex_destroy().

## ◆ starpu_pthread_rwlock_rdlock()

int starpu_pthread_rwlock_rdlock | ( | starpu_pthread_rwlock_t * | rwlock | ) |

Similar to starpu_pthread_mutex_lock().

## ◆ starpu_pthread_rwlock_tryrdlock()

int starpu_pthread_rwlock_tryrdlock | ( | starpu_pthread_rwlock_t * | rwlock | ) |

todo

## ◆ starpu_pthread_rwlock_wrlock()

int starpu_pthread_rwlock_wrlock | ( | starpu_pthread_rwlock_t * | rwlock | ) |

Similar to starpu_pthread_mutex_lock().

## ◆ starpu_pthread_rwlock_trywrlock()

int starpu_pthread_rwlock_trywrlock | ( | starpu_pthread_rwlock_t * | rwlock | ) |

todo

## ◆ starpu_pthread_rwlock_unlock()

int starpu_pthread_rwlock_unlock | ( | starpu_pthread_rwlock_t * | rwlock | ) |

Similar to starpu_pthread_mutex_unlock().

## ◆ starpu_pthread_barrier_init()

int starpu_pthread_barrier_init | ( | starpu_pthread_barrier_t * | barrier,
|  | const starpu_pthread_barrierattr_t * | attr,
|  | unsigned | count
| ) |  |

todo

## ◆ starpu_pthread_barrier_destroy()

int starpu_pthread_barrier_destroy | ( | starpu_pthread_barrier_t * | barrier | ) |

todo

## ◆ starpu_pthread_barrier_wait()

int starpu_pthread_barrier_wait | ( | starpu_pthread_barrier_t * | barrier | ) |

todo

## ◆ starpu_pthread_spin_init()

int starpu_pthread_spin_init | ( | starpu_pthread_spinlock_t * | lock,
|  | int | pshared
| ) |  |

todo

## ◆ starpu_pthread_spin_destroy()

int starpu_pthread_spin_destroy | ( | starpu_pthread_spinlock_t * | lock | ) |

todo

## ◆ starpu_pthread_spin_lock()

int starpu_pthread_spin_lock | ( | starpu_pthread_spinlock_t * | lock | ) |

todo

## ◆ starpu_pthread_spin_trylock()

int starpu_pthread_spin_trylock | ( | starpu_pthread_spinlock_t * | lock | ) |

todo

## ◆ starpu_pthread_spin_unlock()

int starpu_pthread_spin_unlock | ( | starpu_pthread_spinlock_t * | lock | ) |

todo

## ◆ starpu_sleep()

void starpu_sleep | ( | float | nb_sec | ) |

Similar to calling Unix' `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.