---

36.2.7 POSIX Mutexes ¶

A mutex, or “mutual exclusion”, is a way of guaranteeing that only one thread at a time is able to execute a protected bit of code (or access any other resource). Two or more threads trying to execute the same code at the same time, will instead take turns, according to the mutex.

A mutex is much like a spinlock, but implemented in a way that is more appropriate for use in non-realtime threads, and is more resource-conserving.

Function: int pthread_mutex_init (pthread_mutex_t *mutex, const pthread_mutexattr_t *mutexattr) ¶

Initiailizes a mutex. This documentation is a stub. For additional information on this function, consult the manual page pthread_mutex_init(3) See Linux (The Linux Kernel).

Function: int pthread_mutex_destroy (pthread_mutex_t *mutex) ¶

Destroys a no-longer-needed mutex. This documentation is a stub. For additional information on this function, consult the manual page pthread_mutex_destroy(3) See Linux (The Linux Kernel).

Function: int pthread_mutex_lock (pthread_mutex_t *mutex) ¶

Only one thread at a time may lock mutex, and must unlock it when appropriate. If a thread calls pthread_mutex_lock while mutex is locked by another thread, the calling thread will wait until mutex is unlocked, then attempt to lock it. Since there may be many threads waiting at the same time, the calling thread may need to repeat this wait-and-try many times before it successfully locks mutex, at which point the call to pthread_mutex_locks returns succesfully.

This function may fail with the following:

EAGAIN

Too many locks were attempted.

EDEADLK

The calling thread already holds a lock on mutex.

EINVAL

mutex has an invalid kind, or an invalid priority was requested.

ENOTRECOVERABLE

The thread holding the lock died in a way that the system cannot recover from.

EOWNERDEAD

The thread holding the lock died in a way that the system can recover from.

This documentation is a stub. For additional information on this function, consult the manual page pthread_mutex_lock(3) See Linux (The Linux Kernel).

Function: int pthread_mutex_trylock (pthread_mutex_t *mutex) ¶

Like pthread_mutex_lock but if the lock cannot be immediately obtained, returns EBUSY. This documentation is a stub. For additional information on this function, consult the manual page pthread_mutex_trylock(3) See Linux (The Linux Kernel).

Function: int pthread_mutex_unlock (pthread_mutex_t *mutex) ¶

Unlocks mutex. Returns EPERM if the calling thread doesn’t hold the lock on mutex. This documentation is a stub. For additional information on this function, consult the manual page pthread_mutex_unlock(3) See Linux (The Linux Kernel).

Function: int pthread_mutex_clocklock (pthread_mutex_t *mutex, clockid_t clockid, const struct timespec *abstime) ¶

Function: int pthread_mutex_timedlock (pthread_mutex_t *mutex, const struct timespec *abstime) ¶

These two functions act like pthread_mutex_lock with the exception that the call will not wait past time abstime, as reported by clockid or (for pthread_mutex_timedlock) CLOCK_REALTIME. If abstime is reached and the mutex still cannot be locked, an ETIMEDOUT error is returned. If the time had already passed when these functions are called, and the mutex cannot be immediately locked, the function times out immediately.

Function: int pthread_mutexattr_init (const pthread_mutexattr_t *attr) ¶

Initializes attr with default values. This documentation is a stub. For additional information on this function, consult the manual page pthread_mutexattr_init(3) See Linux (The Linux Kernel).

Function: int pthread_mutexattr_destroy (pthread_mutexattr_t *attr) ¶

Destroys attr and releases any resources it may have allocated. This documentation is a stub. For additional information on this function, consult the manual page pthread_mutexattr_destroy(3) See Linux (The Linux Kernel).

Function: int pthread_mutexattr_settype (pthread_mutexattr_t *attr, int kind) ¶

This functions allow you to change what kind of mutex a mutex is, by changing the attributes used to initialize it. The values for kind are:

PTHREAD_MUTEX_NORMAL

No attempt to detect deadlock is performed; a thread will deadlock if it tries to lock this mutex yet already holds a lock to it. Attempting to unlock a mutex not locked by the calling thread results in undefined behavior.

PTHREAD_MUTEX_ERRORCHECK

Attemps to relock a mutex, or unlock a mutex not held, will result in an error.

PTHREAD_MUTEX_RECURSIVE

Attempts to relock a mutex already held succeed, but require a matching number of unlocks to release it. Attempts to unlock a mutex not held will result in an error.

PTHREAD_MUTEX_DEFAULT

Attemps to relock a mutex, or unlock a mutex not held, will result in undefined behavior. This is the default.

Function: int pthread_mutexattr_gettype (const pthread_mutexattr_t *attr, int *kind) ¶

This function gets the kind of mutex mutex is.