A mutex is a construct that prevents two threads from accessing shared data at the same time. When a thread intends to access shared data, it must try to claim the lock on the mutex associated with that data. Only one thread can own the lock, and the other threads will block when trying to claim it, until the original thread releases the lock. At that point, one of the blocked threads will be chosen arbitrarily, unblock, and claim the lock.

<threads.h> defines a type mtx_t to represent a mutex.

#include <threads.h>
int mtx_init(mtx_t *mp, int ty);
void mtx_destroy(mtx_t *mp);

A mutex m must be initialized with mtx_init(&m, ty) before being used by any other function. ty must be either mtx_timed for a mutex that supports timed locks with mtx_timedlock, or mtx_plain for one that does not have to. cy can be bitwise-ORed with mtx_recursive for a mutex that supports recursive locking.

mtx_init returns thrd_success on success, or thrd_error on failure.

Resources allocated for m by mtx_init should be released with mtx_destroy(&m).

#include <threads.h>
int mtx_lock(mtx_t *mp);
int mtx_timedlock(mtx_t *mp, const struct timespec *tp);
int mtx_trylock(mtx_t *mp);

These functions attempt to claim the lock of mutex *mp. If the mutex is already locked by another thread, mtx_lock blocks until the mutex is unlocked, returning thrd_success. mtx_timedlock also blocks until then, returning thrd_success, or until the duration specified by *tp has passed, returning thrd_timedout. mtx_trylock does not block, but returns thrd_busy if it cannot claim the lock. These functions also block or fail respectively if the lock is claimed by the current thread, and the mutex was not initialized with mtx_recursive.

These functions return thrd_error if the lock could not be claimed for some other reason.

mtx_timedlock cannot be called on a mutex that was not initialized with mtx_timed.

#include <threads.h>
int mtx_unlock(mtx_t *mp);

mtx_unlock unlocks the mutex *mp, returning thrd_success on success, and thrd_error on failure. If any other threads are blocked in mtx_lock or mtx_timedlock on *mp, one of them is chosen arbitrarily, unblocks, and claims the lock.

If the mutex was initialized with mtx_recursive, and has been locked n times without being unlocked, it will have to be unlocked n times before other threads are unblocked.