pthread_mutexattr_settype()

Set a mutex type

Synopsis:

#include <pthread.h>

int pthread_mutexattr_settype( 
                      pthread_mutexattr_t * attr, 
                      int type );

Library:

libc

Description:

The pthread_mutexattr_settype() function sets the mutex type attribute in the type parameter. Valid mutex types include:

PTHREAD_MUTEX_NORMAL

No deadlock detection. A thread that attempts to relock this mutex without first unlocking it deadlocks. Attempts to unlock a mutex locked by a different thread or attempts to unlock an unlocked mutex results in undefined behaviour.

PTHREAD_MUTEX_ERRORCHECK

Provides error checking. A thread returns with an error when it attempts to: relock this mutex without first unlocking it, unlock a mutex which another thread has locked returns, or unlock an unlocked mutex.

PTHREAD_MUTEX_RECURSIVE

A thread that attempts to relock this mutex without first unlocking it succeeds in locking the mutex. The relocking deadlock that can occur with mutexes of type PTHREAD_MUTEX_NORMAL can't occur with this mutex type. Multiple locks of this mutex require the same number of unlocks to release the mutex before another thread can acquire the mutex. A thread that attempts to unlock a mutex that another thread has locked, or unlock an unlocked mutex, returns with an error.

PTHREAD_MUTEX_DEFAULT

The default value of the type attribute. Attempts to recursively lock a mutex of this type, or unlock a mutex of this type that isn't locked by the calling thread, or unlock a mutex of this type that isn't locked, results in undefined behaviour.

Returns:

Zero for success, or an error number.

Errors:

EINVAL

The value specified by attr or type is invalid.

Classification:

POSIX 1003.1 (Threads)

Caveats:

An application shouldn't use a PTHREAD_MUTEX_RECURSIVE mutex with condition variables because the implicit unlock performed for a pthread_cond_wait() or pthread_cond_timedwait() may not actually release the mutex (if its been locked multiple times). If this happens, no other thread can satisfy the condition of the predicate.

See also:

pthread_cond_timedwait(), pthread_cond_wait(), pthread_mutexattr_gettype()