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:
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:
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_plainA non-recursive mutex that does not support timeout.
mtx_timedA non-recursive mutex that does support timeout.
mtx_plain | mtx_recursiveA recursive mutex that does not support timeout.
mtx_timed | mtx_recursiveA recursive mutex that does support timeout.
This function returns either thrd_success or thrd_error.
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.
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.
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.
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.
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.