mutex(3synch)

mutex: mutex_init, mutex_lock, mutex_trylock, mutex_unlock, mutex_destroy -- overview of mutual exclusion lock routines

Synopsis

   cc [options] -Kthread file
   
   #include <synch.h>
   

   int mutex_init(mutex_t *mutex, int type, void *arg);
   

   int mutex_lock(mutex_t *mutex);
   

   int mutex_trylock(mutex_t *mutex);
   

   int mutex_unlock(mutex_t *mutex);
   

   int mutex_destroy(mutex_t *mutex);

Description

Mutual exclusion locks, or ``mutexes'', are used to serialize the execution of threads. They are typically used to ensure that only one thread at a time accesses shared data. Note that mutexes protect data only when the convention of acquiring the mutex is faithfully followed before any access of the data.

The Threads Library provides five routines to manipulate mutexes; these are outlined below and described in more detail on individual manual pages.

Parameters

mutex: pointer to mutex to be initialized, locked, unlocked, or destroyed
type: USYNC_THREAD or USYNC_PROCESS
arg: NULL (reserved for future use)

mutex_init(3synch)

mutex_init initializes a mutex to be of type type and in the unlocked state.

mutex_lock(3synch)

mutex_lock locks the mutex pointed to by mutex. If mutex is already locked, the calling thread is blocked until mutex becomes available. When mutex_lock returns successfully, the caller has locked mutex.

mutex_trylock(3synch)

mutex_trylock attempts once to lock the mutex pointed to by mutex.

If mutex is available, mutex_trylock will return successfully with mutex locked. If mutex is already locked, mutex_trylock immediately returns EBUSY to the caller without acquiring mutex or blocking.

mutex_unlock(3synch)

mutex_unlock unlocks the mutex pointed to by mutex.

If there are one or more threads waiting for mutex when mutex_unlock is called, at least one waiting thread is allowed to try again to lock mutex.

mutex_destroy(3synch)

mutex_destroy destroys the mutex pointed to by mutex. This includes invalidating mutex and freeing any associated implementation-allocated dynamic resources.

USYNC_THREAD and USYNC_PROCESS mutexes

Mutexes are initialized to be one of two types: USYNC_THREAD or USYNC_PROCESS. USYNC_THREAD mutexes are available only to threads within the current process. USYNC_PROCESS mutexes can be used by threads in different processes.

General information

Mutexes must be initialized, either with mutex_init(3synch) or statically (see mutex_init), before being passed to any of the other mutex routines.

Locks acquired with mutex_lock or mutex_trylock must be released with mutex_unlock.

From the point of view of the caller, mutex_lock is atomic: even if interrupted by a signal or forkall (see fork(2)), mutex_lock will not return until it holds the locked mutex. As a consequence, if mutex_lock is interrupted, an error indication such as EINTR is never returned to the caller.

Warnings

Operations on mutexes are not recursive--a thread can deadlock if it attempts to relock a mutex that it already has locked.

If a thread exits while holding a mutex, the mutex will not be unlocked, and other threads waiting for the mutex will wait forever. Similarly, if a process exits while holding a USYNC_PROCESS mutex, the mutex will not be unlocked, and other processes or threads waiting for the mutex will wait forever.

References

fork(2), Intro(3synch), mutex_init(3synch), mutex_destroy(3synch), mutex_lock(3synch), mutex_trylock(3synch), mutex_unlock(3synch), rmutex(3synch)