pthread_mutexattr_init, pthread_mutexattr_destroy, pthread_mutexattr_settype, pthread_mutexattr_gettype - mutex creation attributes
#include <pthread.h>
int pthread_mutexattr_init(pthread_mutexattr_t *attr);
int pthread_mutexattr_destroy(pthread_mutexattr_t *attr);
int pthread_mutexattr_settype(pthread_mutexattr_t *attr, int type);
int pthread_mutexattr_gettype(const pthread_mutexattr_t *attr, int *type);
int pthread_mutexattr_setkind_np(pthread_mutexattr_t *attr, int type);
int pthread_mutexattr_getkind_np(const pthread_mutexattr_t *attr, int *type);
int pthread_mutexattr_setrobust(pthread_mutexattr_t *attr, int robust);
int pthread_mutexattr_getrobust(pthread_mutexattr_t *attr, int *robust);
Mutex attributes can be specified at mutex creation time, by passing a mutex attribute object as second argument to pthread_mutex_init(3) . Passing NULL is equivalent to passing a mutex attribute object with all attributes set to their default values.
pthread_mutexattr_init initializes the mutex attribute object attr and fills it with default values for the attributes.
pthread_mutexattr_destroy destroys a mutex attribute object, which must not be reused until it is reinitialized.
pthread_mutexattr_settype sets the mutex type attribute in attr to the value specified by type.
pthread_mutexattr_gettype retrieves the current value of the mutex kind attribute in attr and stores it in the location pointed to by type.
Pthreads-w32 also recognises the following equivalent functions that are used in Linux:
pthread_mutexattr_setkind_np is an alias for pthread_mutexattr_settype.
pthread_mutexattr_getkind_np is an alias for pthread_mutexattr_gettype.
The following mutex types are supported:
PTHREAD_MUTEX_NORMAL - for ‘‘fast’’ mutexes.
PTHREAD_MUTEX_RECURSIVE - for ‘‘recursive’’ mutexes.
PTHREAD_MUTEX_ERRORCHECK - for ‘‘error checking’’ mutexes.
The mutex type determines what happens if a thread attempts to lock a mutex it already owns with pthread_mutex_lock(3) . If the mutex is of the “normal” or “fast” type, pthread_mutex_lock(3) simply suspends the calling thread forever. If the mutex is of the ‘‘error checking’’ type, pthread_mutex_lock(3) returns immediately with the error code EDEADLK. If the mutex is of the ‘‘recursive’’ type, the call to pthread_mutex_lock(3) returns immediately with a success return code. The number of times the thread owning the mutex has locked it is recorded in the mutex. The owning thread must call pthread_mutex_unlock(3) the same number of times before the mutex returns to the unlocked state.
The default mutex type is PTHREAD_MUTEX_NORMAL
Pthreads-w32 also recognises the following equivalent types that are used by Linux:
PTHREAD_MUTEX_FAST_NP – equivalent to PTHREAD_MUTEX_NORMAL
PTHREAD_MUTEX_RECURSIVE_NP
PTHREAD_MUTEX_ERRORCHECK_NP
pthread_mutexattr_setrobust sets the robustness attribute to the value given by robust.
pthread_mutexattr_getrobust returns the current robustness value to the location given by *robust.
The possible values for robust are:
PTHREAD_MUTEX_STALLED - when the owner of the mutex terminates without unlocking the mutex, all subsequent calls to pthread_mutex_*lock() are blocked from progress in an unspecified manner.
PTHREAD_MUTEX_ROBUST - when the owner of the mutex terminates without unlocking the mutex, the mutex is unlocked. The next owner of this mutex acquires the mutex with an error return of EOWNERDEAD.
On success all functions return 0, otherwise they return an error code as follows:
pthread_mutexattr_init
ENOMEM - insufficient memory for attr.
pthread_mutexattr_destroy
EINVAL - attr is invalid.
pthread_mutexattr_gettype
EINVAL - attr is invalid.
pthread_mutexattr_settype
pthread_mutexattr_getrobust
EINVAL – attr or robust is invalid.
pthread_mutexattr_setrobust
EINVAL – attr or robust is invalid.
Xavier Leroy <Xavier.Leroy@inria.fr>
Modified by Ross Johnson for use with Pthreads-w32.
pthread_mutex_init(3) , pthread_mutex_lock(3) , pthread_mutex_unlock(3) .
For speed, Pthreads-w32 never checks the thread ownership of non-robust mutexes of type PTHREAD_MUTEX_NORMAL (or PTHREAD_MUTEX_FAST_NP) when performing operations on the mutex. It is therefore possible for one thread to lock such a mutex and another to unlock it.
When developing code, it is a common precaution to substitute the error checking type, then drop in the normal type for release if the extra performance is required.