ISO C Mutexes (The GNU C Library)

#### 36.1.4 Mutexes ¶

To have better control of resources and how threads access them, the GNU C Library implements a mutex object, which can help avoid race conditions and other concurrency issues. The term “mutex” refers to mutual exclusion.

The fundamental data type for a mutex is the `mtx_t`:

Data Type: mtx_t ¶

  The `mtx_t` data type uniquely identifies a mutex object.

The ISO C standard defines several types of mutexes. They are represented by the following symbolic constants:

`mtx_plain` ¶

  A mutex that does not support timeout, or test and return.

`mtx_recursive` ¶

  A mutex that supports recursive locking, which means that the owning thread can lock it more than once without causing deadlock.

`mtx_timed` ¶

  A mutex that supports timeout.

The following functions are used for working with mutexes:

Function: `int` mtx_init `(mtx_t *mutex, int type)` ¶

  Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

  `mtx_init` creates a new mutex object with type type. The object pointed to by mutex is set to the identifier of the newly created mutex.

  Not all combinations of mutex types are valid for the `type` argument. Valid uses of mutex types for the `type` argument are:

  `mtx_plain`

    A non-recursive mutex that does not support timeout.

  `mtx_timed`

    A non-recursive mutex that does support timeout.

  `mtx_plain | mtx_recursive`

    A recursive mutex that does not support timeout.

  `mtx_timed | mtx_recursive`

    A recursive mutex that does support timeout.

  This function returns either `thrd_success` or `thrd_error`.

Function: `int` mtx_lock `(mtx_t *mutex)` ¶

  Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock | See POSIX Safety Concepts.

  `mtx_lock` blocks the current thread until the mutex pointed to by mutex is locked. The behavior is undefined if the current thread has already locked the mutex and the mutex is not recursive.

  Prior calls to `mtx_unlock` on the same mutex synchronize-with this operation (if this operation succeeds), and all lock/unlock operations on any given mutex form a single total order (similar to the modification order of an atomic).

  This function returns either `thrd_success` or `thrd_error`.

Function: `int` mtx_timedlock `(mtx_t *restrict mutex, const struct timespec *restrict time_point)` ¶

  Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock | See POSIX Safety Concepts.

  `mtx_timedlock` blocks the current thread until the mutex pointed to by mutex is locked or until the calendar time pointed to by time_point has been reached. Since this function takes an absolute time, if a duration is required, the calendar time must be calculated manually. See Time Basics, and Calendar Time.

  If the current thread has already locked the mutex and the mutex is not recursive, or if the mutex does not support timeout, the behavior of this function is undefined.

  Prior calls to `mtx_unlock` on the same mutex synchronize-with this operation (if this operation succeeds), and all lock/unlock operations on any given mutex form a single total order (similar to the modification order of an atomic).

  This function returns either `thrd_success` or `thrd_error`.

Function: `int` mtx_trylock `(mtx_t *mutex)` ¶

  Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock | See POSIX Safety Concepts.

  `mtx_trylock` tries to lock the mutex pointed to by mutex without blocking. It returns immediately if the mutex is already locked.

  Prior calls to `mtx_unlock` on the same mutex synchronize-with this operation (if this operation succeeds), and all lock/unlock operations on any given mutex form a single total order (similar to the modification order of an atomic).

  This function returns `thrd_success` if the lock was obtained, `thrd_busy` if the mutex is already locked, and `thrd_error` on failure.

Function: `int` mtx_unlock `(mtx_t *mutex)` ¶

  Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

  `mtx_unlock` unlocks the mutex pointed to by mutex. The behavior is undefined if the mutex is not locked by the calling thread.

  This function synchronizes-with subsequent `mtx_lock`, `mtx_trylock`, and `mtx_timedlock` calls on the same mutex. All lock/unlock operations on any given mutex form a single total order (similar to the modification order of an atomic).

  This function returns either `thrd_success` or `thrd_error`.

Function: `void` mtx_destroy `(mtx_t *mutex)` ¶

  Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

  `mtx_destroy` destroys the mutex pointed to by mutex. If there are any threads waiting on the mutex, the behavior is undefined.