mutex(3T)
NAME
mutex, mutex_init, mutex_destroy, mutex_lock, mutex_trylock, mutex_unlock − mutual exclusion locks
SYNOPSIS
#include <synch.h>
int mutex_init(mutex_t ∗mp, int type, void ∗ arg);
int mutex_destroy(mutex_t ∗mp);
int mutex_lock(mutex_t ∗mp);
int mutex_trylock(mutex_t ∗mp);
int mutex_unlock(mutex_t ∗mp);
MT-LEVEL
MT-Safe
DESCRIPTION
Mutual exclusion locks (mutexes) are used to serialize the execution of threads. They are typically used to ensure that only one thread executes a critical section of code at any one time (mutual exclusion).
Mutexes can be used to synchronize threads in this process and other processes if they are allocated in memory that is writable and shared among the cooperating processes (see mmap(2)) and have been initialized for this behavior.
Mutexes must be initialized before use. mutex_init() initializes the mutex pointed to by mp. A mutex can potentially have several different types of behavior, specified by type. No current type uses arg although a future type may specify additional behavior parameters via arg. type may be one of the following:
USYNC_PROCESS The mutex can be used to synchronize threads in this process and other processes. Only one process should initialize the mutex. arg is ignored.
USYNC_THREAD The mutex can be used to synchronize threads in this process, only. arg is ignored.
Mutexes may also be initialized by allocation in zeroed memory. In this case a type of USYNC_THREAD is assumed. Multiple threads must not initialize the same mutex simultaneously. A mutex lock must not be re-initialized while other threads may be using it.
mutex_destroy() destroys any state associated with the mutex pointed to by mp. The space for storing the mutex is not freed.
mutex_lock() locks the mutex pointed to by mp. If the mutex is already locked, the calling thread blocks until the mutex becomes available. When mutex_lock() returns, the mutex is locked and the calling thread is the owner.
mutex_trylock() attempts to lock the mutex pointed to by mp. If the mutex is already locked it returns with an error. Otherwise the mutex is locked and the calling thread is the owner.
mutex_unlock() unlocks the mutex pointed to by mp. The mutex must be locked and the calling thread must be the one that last locked the mutex (the owner). If any other threads are waiting for the mutex to become available, one of them is unblocked. If the calling thread is not the owner of the lock, no error status is returned, and the behavior of the program is undefined.
RETURN VALUES
Zero is returned when successful. A non-zero value indicates an error.
ERRORS
If any of the following conditions are detected, these functions fail and return the corresponding value:
EINVAL Invalid argument.
EFAULT mp or arg points to an illegal address.
If any of the following conditions are detected, mutex_trylock() fails and returns the corresponding value:
EBUSY The mutex pointed to by mp was already locked.
SEE ALSO
NOTES
In the current implementation, mutex_lock(), mutex_unlock(), and mutex_trylock() do not validate the mutex type. Therefore, EINVAL is not returned for an uninitialized mutex or for a mutex with an invalid type. The behavior of these interfaces for mutexes containing an invalid type is unspecified.
For example, the following call to mutex_lock() might “hang”. Since mutex is allocated from the stack and is not initialized, it may have “junk” data in it. mutex needs to be initialized using mutex_init().
int global;
main()
{
mutex_t mutex;
/∗
∗ The address of this mutex is passed to threads created from
∗ main(). NOTE: this is not recommended style.
∗/
...
if (mutex_lock(&mutex) == 0) { /∗ this call may hang ∗/
global++;
mutex_unlock(&mutex);
} else
printf("mutex_lock() failed\n");
...
}
Instead, mutex should first be initialized using mutex_init().
int global;
main()
{
mutex_t mutex;
...
mutex_init(&mutex, USYNC_THREAD, NULL);
mutex_lock(&mutex); /∗ This call is now guaranteed to work ∗/
global++;
mutex_unlock(&mutex);
}
By default, there is no defined order of acquisition if multiple threads are waiting for a mutex.
These interfaces are also available via:
#include <thread.h>
SunOS 5.4 — Last change: 29 Mar 1994