#### 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.