Figure 5, Table 5, Routines for Mutual Exclusion Locks lists the functions that manipulate mutex locks.
|
The default scheduling policy, SCHED_OTHER, does not specify the order in which threads can acquire a lock. When multiple SCHED_OTHER threads are waiting for a mutex, the order of acquisition is undefined. Under the SCHED_FIFO and SCHED_RR real-time scheduling policies, the behavior is to unblock waiting threads in priority order.
Use pthread_mutex_init(3C) to initialize the mutex pointed at by mp to its default value or to specify mutex attributes that have already been set with pthread_mutexattr_init(). The default value for mattr is NULL.
int pthread_mutex_init(pthread_mutex_t *restrict mp,
const pthread_mutexattr_t *restrict mattr);
#include <pthread.h> pthread_mutex_t mp = PTHREAD_MUTEX_INITIALIZER; pthread_mutexattr_t mattr; int ret; /* initialize a mutex to its default value */ ret = pthread_mutex_init(&mp, NULL); /* initialize a mutex */ ret = pthread_mutex_init(&mp, &mattr);
When the mutex is initialized, the mutex is in an unlocked state. The mutex can be in memory that is shared between processes or in memory private to a process.
The effect of mattr set to NULL is the same as passing the address of a default mutex attribute object, but without the memory overhead.
Use the macro PTHREAD_MUTEX_INITIALIZER to initialize statically defined mutexes to their default attributes.
You can use the PTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP and the PTHREAD_ERRORCHECK_MUTEX_INITIALIZER_NP static initializers for recursive mutex and error check mutex respectively.
Do not reinitialize or destroy a mutex lock while other threads are using the mutex. Program failure results if either action is not done correctly. If a mutex is reinitialized or destroyed, the application must be sure the mutex is not currently in use.
pthread_mutex_init() returns zero after completing successfully. Any other return value indicates that an error occurred. When any of the following conditions occurs, the function fails and returns the corresponding value.
EBUSY
Description: The implementation has detected an attempt to reinitialize the object referenced by mp, a previously initialized but not yet destroyed mutex.
EINVAL
Description: The mattr attribute value is invalid. The mutex has not been modified.
EFAULT
Description: The address for the mutex pointed at by mp is invalid.
If the owner of a robust mutex terminates without unlocking the mutex, the mutex is unlocked and marked inconsistent. The next owner acquires the lock with an EOWNERDEAD return code.
pthread_mutex_consistent() makes the mutex object, mutex, consistent after the death of its owner.
#include <pthread.h> int pthread_mutex_consistent(pthread_mutex_t *mutex);
Call pthread_mutex_lock() to acquire the inconsistent mutex. The EOWNWERDEAD return value indicates an inconsistent mutex.
Call pthread_mutex_consistent() while holding the mutex acquired by a previous call to pthread_mutex_lock().
The critical section protected by the mutex might have been left in an inconsistent state by a failed owner. In this case, make the mutex consistent only if you can make the critical section protected by the mutex consistent.
Calls to pthread_mutex_lock(), pthread_mutex_unlock(), and pthread_mutex_trylock() for a consistent mutex behave in the normal manner.
The behavior of pthread_mutex_consistent() for a mutex that is not inconsistent, or is not held, is undefined.
pthread_mutex_consistent() returns zero after completing successfully. Any other return value indicates that an error occurred.
pthread_mutex_consistent() fails if the following condition occurs:
EINVAL
Description: The current thread does not own the mutex or the mutex is not a PTHREAD_MUTEX_ROBUST mutex having an inconsistent state.
Use pthread_mutex_lock(3C) to lock the mutex pointed to by mutex.
int pthread_mutex_lock(pthread_mutex_t *mutex);
#include <pthread.h> pthread_mutex_t mutex; int ret; ret = pthread_ mutex_lock(&mp); /* acquire the mutex */
When pthread_mutex_lock() returns, the mutex is locked. The calling thread is the owner. If the mutex is already locked and owned by another thread, the calling thread blocks until the mutex becomes available.
If the mutex type is PTHREAD_MUTEX_NORMAL, deadlock detection is not provided. Attempting to relock the mutex causes deadlock. If a thread attempts to unlock a mutex not locked by the thread or a mutex that is unlocked, undefined behavior results.
If the mutex type is PTHREAD_MUTEX_ERRORCHECK, then error checking is provided. If a thread attempts to relock a mutex that the thread has already locked, an error is returned. If a thread attempts to unlock a mutex not locked by the thread or a mutex that is unlocked, an error is returned.
If the mutex type is PTHREAD_MUTEX_RECURSIVE, then the mutex maintains the concept of a lock count. When a thread successfully acquires a mutex for the first time, the lock count is set to 1. Every time a thread relocks this mutex, the lock count is incremented by 1. Every time the thread unlocks the mutex, the lock count is decremented by 1. When the lock count reaches 0, the mutex becomes available for other threads to acquire. If a thread attempts to unlock a mutex not locked by the thread or a mutex that is unlocked, an error is returned.
The mutex type PTHREAD_MUTEX_DEFAULT is the same as PTHREAD_MUTEX_NORMAL.
pthread_mutex_lock() returns zero after completing successfully. Any other return value indicates that an error occurred. When any of the following conditions occurs, the function fails and returns the corresponding value.
EAGAIN
Description: The mutex could not be acquired because the maximum number of recursive locks for mutex has been exceeded.
EDEADLK
Description: The current thread already owns the mutex.
If the mutex was initialized with the PTHREAD_MUTEX_ROBUSTrobustness attribute, pthread_mutex_lock() may return one of the following values:
EOWNERDEAD
Description: The last owner of this mutex terminated while holding the mutex. This mutex is now owned by the caller. The caller must attempt to make the state protected by the mutex consistent. If the caller is able to make the state consistent, call pthread_mutex_consistent() for the mutex and unlock the mutex. Subsequent calls to pthread_mutex_lock() behave normally. If the caller is unable to make the state consistent, do not call pthread_mutex_consistent() for the mutex. Unlock the mutex instead. Subsequent calls to pthread_mutex_lock() fail to acquire the mutex and return an ENOTRECOVERABLE error code. If the owner that acquired the lock with EOWNERDEAD terminates while holding the mutex, the next owner acquires the lock with EOWNERDEAD.
ENOTRECOVERABLE
Description: The mutex you are trying to acquire was protecting state left irrecoverable by the mutex's previous owner. The mutex has not been acquired. This irrecoverable condition can occur when:
The lock was previously acquired with EOWNERDEAD
The owner was unable to cleanup the state
The owner unlocked the mutex without making the mutex state consistent
ENOMEM
Description: The limit on the number of simultaneously held mutexes has been exceeded.
Use pthread_mutex_unlock(3C) to unlock the mutex pointed to by mutex.
int pthread_mutex_unlock(pthread_mutex_t *mutex);
#include <pthread.h> pthread_mutex_t mutex; int ret; ret = pthread_mutex_unlock(&mutex); /* release the mutex */
pthread_mutex_unlock() releases the mutex object referenced by mutex. The manner in which a mutex is released is dependent upon the mutex's type attribute. If threads are blocked on the mutex object when pthread_mutex_unlock() is called and the mutex becomes available, the scheduling policy determines which thread acquires the mutex. For PTHREAD_MUTEX_RECURSIVE mutexes, the mutex becomes available when the count reaches zero and the calling thread no longer has any locks on this mutex.
pthread_mutex_unlock() returns zero after completing successfully. Any other return value indicates that an error occurred. When the following condition occurs, the function fails and returns the corresponding value.
EPERM
Description: The current thread does not own the mutex.
Use pthread_mutex_trylock(3C) to attempt to lock the mutex pointed to by mutex, and return immediately if the mutex is already locked.
int pthread_mutex_trylock(pthread_mutex_t *mutex);
#include <pthread.h> pthread_mutex_t mutex; int ret; ret = pthread_mutex_trylock(&mutex); /* try to lock the mutex */
pthread_mutex_trylock() is a nonblocking version of pthread_mutex_lock(). If the mutex object referenced by mutex is currently locked by any thread, including the current thread, the call returns immediately. Otherwise, the mutex is locked and the calling thread is the owner.
pthread_mutex_trylock() returns zero after completing successfully. Any other return value indicates that an error occurred. When any of the following conditions occurs, the function fails and returns the corresponding value.
EBUSY
Description: The mutex could not be acquired because the mutex pointed to by mutex was already locked.
EAGAIN
Description: The mutex could not be acquired because the maximum number of recursive locks for mutex has been exceeded.
If the symbol _POSIX_THREAD_PRIO_INHERIT is defined, the mutex is initialized with the protocol attribute value PTHREAD_PRIO_INHERIT . Additionally, if the robustness argument of pthread_mutexattr_setrobust() is PTHREAD_MUTEX_ROBUST, the function fails and returns one of the following values:
EOWNERDEAD
Description: See the discussion in pthread_mutex_lock Return Values.
ENOTRECOVERABLE
Description: See the discussion in pthread_mutex_lock Return Values.
ENOMEM
Description: The limit on the number of simultaneously held mutexes has been exceeded.
Use the pthread_mutex_timedlock(3C) function to attempt until a specified time to lock a mutex object.
This function works as the pthread_mutex_lock() function does, except that it does not block indefinitely. If the mutex is already locked, the calling thread is blocked until the mutex becomes available, but only until the timeout is reached. If the timeout occurs before the mutex becomes available, the function returns.
int pthread_mutex_timedlock(pthread_mutex_t *restrict mutex,
const struct timespec *restrict abs_timeout);
#include <pthread.h> #include <time.h> pthread_mutex_t mutex; timestruct_t abs_timeout; int ret; ret = pthread_mutex_timedlock(&mutex, &abs_timeout);
The pthread_mutex_timedlock() function return 0 if it locks the mutex successfully. Otherwise, an error number is returned to indicate the error.
EINVAL
Description: The mutex was created with the protocol attribute having the value PTHREAD_PRIO_PROTECT and the calling thread's priority is higher than the mutex's current priority ceiling.
Description: The value specified by mutex does not refer to an initialized mutex object.
Description: The process or thread would have blocked, and the abs_timeout parameter specified a nanoseconds field value less than 0 or greater than or equal to 1000 million.
ETIMEDOUT
Description: The mutex could not be locked before the specified timeout expired.
See the discussion in pthread_mutex_lock Return Values.
Use the pthread_mutex_reltimedlock_np(3C) function to attempt until a specified amount of time elapses to lock a mutex object.
The timeout expires when the time interval specified by rel_timeout passes, as measured by the CLOCK_REALTIME clock, or if the time interval specified by rel_timeout is negative at the time of the call.
int pthread_mutex_reltimedlock_np(pthread_mutex_t *restrict mutex,
const struct timespec *restrict rel_timeout);
#include <pthread.h> #include <time.h> pthread_mutex_t mutex; timestruct_t rel_timeout; int ret; ret = pthread_mutex_reltimedlock_np(&mutex, &rel_timeout);
The pthread_mutex_reltimedlock_np() function returns 0 if it locks the mutex successfully. Otherwise, an error number is returned to indicate the error.
EINVAL
Description: The mutex was created with the protocol attribute having the value PTHREAD_PRIO_PROTECT and the calling thread's priority is higher than the mutex's current priority ceiling.
Description: The value specified by mutex does not refer to an initialized mutex object.
Description: The process or thread would have blocked, and the abs_timeout parameter specified a nanoseconds field value less than 0 or greater than or equal to 1000 million.
ETIMEDOUT
Description: The mutex could not be locked before the specified timeout expired.
See the discussion in pthread_mutex_lock Return Values.
Use pthread_mutex_destroy(3C) to destroy any state that is associated with the mutex pointed to by mp.
int pthread_mutex_destroy(pthread_mutex_t *mp);
#include <pthread.h> pthread_mutex_t mp; int ret; ret = pthread_mutex_destroy(&mp); /* mutex is destroyed */
Note that the space for storing the mutex is not freed.
pthread_mutex_destroy() returns zero after completing successfully. Any other return value indicates that an error occurred. When any of the following conditions occur, the function fails and returns the corresponding value.
EINVAL
Description: The value specified by mp does not refer to an initialized mutex object.
Example 8, Mutex Lock Example shows some code fragments with mutex locking.
Example 8 Mutex Lock Example#include <pthread.h>
pthread_mutex_t count_mutex;
long long count;
void
increment_count()
{
pthread_mutex_lock(&count_mutex);
count = count + 1;
pthread_mutex_unlock(&count_mutex);
}
long long
get_count()
{
long long c;
pthread_mutex_lock(&count_mutex);
c = count;
pthread_mutex_unlock(&count_mutex);
return (c);
}
The two functions in Example 8, Mutex Lock Example use the mutex lock for different purposes. The increment_count() function uses the mutex lock to ensure an atomic update of the shared variable. The get_count() function uses the mutex lock to guarantee that the 64-bit quantity count is read atomically. On a 32-bit architecture, a long long is really two 32-bit quantities.
When you read an integer value, the operation is atomic because an integer is the common word size on most machines.
Occasionally, you might want to access two resources at once. Perhaps you are using one of the resources, and then discover that the other resource is needed as well. A problem exists if two threads attempt to claim both resources but lock the associated mutexes in different orders. For example, if the two threads lock mutexes 1 and 2 respectively, a deadlock occurs when each attempts to lock the other mutex. Example 9, Deadlock Scenarios shows possible deadlock scenarios.
Example 9 Deadlock Scenarios
|
The best way to avoid this problem is to make sure that when threads lock multiple mutexes, the threads do so in the same order. When locks are always taken in a prescribed order, deadlock should not occur. This technique, known as lock hierarchies, orders the mutexes by logically assigning numbers to the mutexes.
Also, honor the restriction that you cannot take a mutex that is assigned n when you are holding any mutex assigned a number that is greater than n.
However, this technique cannot always be used. Sometimes, you must take the mutexes in an order other than prescribed. To prevent deadlock in such a situation, use pthread_mutex_trylock(). One thread must release its mutexes when the thread discovers that deadlock would otherwise be inevitable.
Example 10 Conditional Locking
|
In Example 10, Conditional Locking, thread1 locks mutexes in the prescribed order, but thread2 takes the mutexes out of order. To make certain that no deadlock occurs, thread2 has to take mutex1 very carefully. If thread2 blocks while waiting for the mutex to be released, thread2 is likely to have just entered into a deadlock with thread1.
To ensure that thread2 does not enter into a deadlock, thread2 calls pthread_mutex_trylock(), which takes the mutex if available. If the mutex is not available, thread2 returns immediately, reporting failure. At this point, thread2 must release mutex2. Thread1 can now lock mutex2, and then release both mutex1 and mutex2.
Example 11, Singly-Linked List Structure and Example 12, Singly-Linked List With Nested Locking show how to take three locks at once. Deadlock is prevented by taking the locks in a prescribed order.
Example 11 Singly-Linked List Structuretypedef struct node1 {
int value;
struct node1 *link;
pthread_mutex_t lock;
} node1_t;
node1_t ListHead;
This example uses a singly linked list structure with each node that contains a mutex. To remove a node from the list, first search the list starting at ListHead until the desired node is found. ListHead is never removed.
To protect this search from the effects of concurrent deletions, lock each node before any of its contents are accessed. Because all searches start at ListHead, a deadlock cannot occur because the locks are always taken in list order.
When the desired node is found, lock both the node and its predecessor since the change involves both nodes. Because the predecessor's lock is always taken first, you are again protected from deadlock. Example 12, Singly-Linked List With Nested Locking shows the C code to remove an item from a singly-linked list.
Example 12 Singly-Linked List With Nested Lockingnode1_t *delete(int value)
{
node1_t *prev, *current;
prev = &ListHead;
pthread_mutex_lock(&prev->lock);
while ((current = prev->link) != NULL) {
pthread_mutex_lock(¤t->lock);
if (current->value == value) {
prev->link = current->link;
pthread_mutex_unlock(¤t->lock);
pthread_mutex_unlock(&prev->lock);
current->link = NULL;
return(current);
}
pthread_mutex_unlock(&prev->lock);
prev = current;
}
pthread_mutex_unlock(&prev->lock);
return(NULL);
}
Example 13, Circular-Linked List Structure modifies the previous list structure by converting the list structure into a circular list. Because a distinguished head node no longer exists, a thread can be associated with a particular node and can perform operations on that node and its neighbor Lock hierarchies do not work easily here because the obvious hierarchy, following the links, is circular.
Example 13 Circular-Linked List Structuretypedef struct node2 {
int value;
struct node2 *link;
pthread_mutex_t lock;
} node2_t;
Here is the C code that acquires the locks on two nodes and performs an operation that involves both locks.
Example 14 Circular Linked List With Nested Lockingvoid Hit Neighbor(node2_t *me) {
while (1) {
pthread_mutex_lock(&me->lock);
if (pthread_mutex_trylock(&me->link->lock)!= 0) {
/* failed to get lock */
pthread_mutex_unlock(&me->lock);
continue;
}
break;
}
me->link->value += me->value;
me->value /=2;
pthread_mutex_unlock(&me->link->lock);
pthread_mutex_unlock(&me->lock);
}