StarPU Handbook

- Main Page
- Related Pages
- Modules
- Data Structures
- Files

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Groups Pages
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 (Simulated Performance). 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_on (char *name, starpu_pthread_t *thread, const starpu_pthread_attr_t *attr, void *(*start_routine)(void *), void *arg, int where)
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_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_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_wrlock (starpu_pthread_rwlock_t *rwlock)
int | starpu_pthread_rwlock_unlock (starpu_pthread_rwlock_t *rwlock)

## 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 (Simulated Performance).

## Macro Definition Documentation

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

This macro calls the function starpu_pthread_create_on() and aborts on error.

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

This macro calls the function starpu_pthread_create() and aborts on error.

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

This macro calls the function starpu_pthread_mutex_init() and aborts on error.

#define STARPU_PTHREAD_MUTEX_DESTROY | ( |  | mutex | ) |

This macro calls the function starpu_pthread_mutex_destroy() and aborts on error.

#define STARPU_PTHREAD_MUTEX_LOCK | ( |  | mutex | ) |

This macro calls the function starpu_pthread_mutex_lock() and aborts on error.

#define STARPU_PTHREAD_MUTEX_UNLOCK | ( |  | mutex | ) |

This macro calls the function starpu_pthread_mutex_unlock() and aborts on error.

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

This macro calls the function starpu_pthread_key_create() and aborts on error.

#define STARPU_PTHREAD_KEY_DELETE | ( |  | key | ) |

This macro calls the function starpu_pthread_key_delete() and aborts on error.

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

This macro calls the function starpu_pthread_setspecific() and aborts on error.

#define STARPU_PTHREAD_GETSPECIFIC | ( |  | key | ) |

This macro calls the function starpu_pthread_getspecific() and aborts on error.

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

This macro calls the function starpu_pthread_rwlock_init() and aborts on error.

#define STARPU_PTHREAD_RWLOCK_RDLOCK | ( |  | rwlock | ) |

This macro calls the function starpu_pthread_rwlock_rdlock() and aborts on error.

#define STARPU_PTHREAD_RWLOCK_WRLOCK | ( |  | rwlock | ) |

This macro calls the function starpu_pthread_rwlock_wrlock() and aborts on error.

#define STARPU_PTHREAD_RWLOCK_UNLOCK | ( |  | rwlock | ) |

This macro calls the function starpu_pthread_rwlock_unlock() and aborts on error.

#define STARPU_PTHREAD_RWLOCK_DESTROY | ( |  | rwlock | ) |

This macro calls the function starpu_pthread_rwlock_destroy() and aborts on error.

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

This macro calls the function starpu_pthread_cond_init() and aborts on error.

#define STARPU_PTHREAD_COND_DESTROY | ( |  | cond | ) |

This macro calls the function starpu_pthread_cond_destroy() and aborts on error.

#define STARPU_PTHREAD_COND_SIGNAL | ( |  | cond | ) |

This macro calls the function starpu_pthread_cond_signal() and aborts on error.

#define STARPU_PTHREAD_COND_BROADCAST | ( |  | cond | ) |

This macro calls the function starpu_pthread_cond_broadcast() and aborts on error.

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

This macro calls the function starpu_pthread_cond_wait() and aborts on error.

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

This macro calls the function starpu_pthread_barrier_init() and aborts on error.

#define STARPU_PTHREAD_BARRIER_DESTROY | ( |  | barrier | ) |

This macro calls the function starpu_pthread_barrier_destroy() and aborts on error.

#define STARPU_PTHREAD_BARRIER_WAIT | ( |  | barrier | ) |

This macro calls the function starpu_pthread_barrier_wait() and aborts on error.

STARPU_PTHREAD_MUTEX_INITIALIZER

This macro initializes the mutex given in parameter.

STARPU_PTHREAD_COND_INITIALIZER

This macro initializes the condition variable given in parameter.

## Function Documentation

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

This function starts 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`.

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

This function waits 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.

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

This function initializes the thread attributes object pointed to by `attr` with default attribute values.

It does not do anything when the simulated performance mode is enabled (Simulated Performance).

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

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 (Simulated Performance).

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

This function sets 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.

It does not do anything when the simulated performance mode is enabled (Simulated Performance).

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

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

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

This function destroys a mutex object, freeing the resources it might hold. The mutex must be unlocked on entrance.

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

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.

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

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

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

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.

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

This function allocates a new TSD key. The key is stored in the location pointed to by `key`.

int starpu_pthread_key_delete | ( | starpu_pthread_key_t | key | ) |

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.

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

This function changes the value associated with `key` in the calling thread, storing the given `pointer` instead.

* starpu_pthread_getspecific | ( | starpu_pthread_key_t | key | ) |

This function returns the value associated with `key` on success, and NULL on error.

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

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

starpu_pthread_cond_signal | ( | starpu_pthread_cond_t * | cond | ) |

This function restarts 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 not specified which.

starpu_pthread_cond_broadcast | ( | starpu_pthread_cond_t * | cond | ) |

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

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

This function atomically unlocks the mutex (as per starpu_pthread_mutex_unlock()) and waits 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()).

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

This function atomically unlocks `mutex` and waits on `cond`, as starpu_pthread_cond_wait() does, but it also bounds the duration of the wait.

starpu_pthread_cond_destroy | ( | starpu_pthread_cond_t * | cond | ) |

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.

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

This function is the same as starpu_pthread_mutex_init().

starpu_pthread_rwlock_destroy | ( | starpu_pthread_rwlock_t * | rwlock | ) |

This function is the same as starpu_pthread_mutex_destroy().

starpu_pthread_rwlock_rdlock | ( | starpu_pthread_rwlock_t * | rwlock | ) |

This function is the same as starpu_pthread_mutex_lock().

starpu_pthread_rwlock_wrlock | ( | starpu_pthread_rwlock_t * | rwlock | ) |

This function is the same as starpu_pthread_mutex_lock().

starpu_pthread_rwlock_unlock | ( | starpu_pthread_rwlock_t * | rwlock | ) |

This function is the same as starpu_pthread_mutex_unlock().