Skip Navigation Links | |
Exit Print View | |
![]() |
Multithreaded Programming Guide Oracle Solaris 11 Express 11/10 |
1. Covering Multithreading Basics
4. Programming with Synchronization Objects
Mutual Exclusion Lock Attributes
Initializing a Mutex Attribute Object
pthread_mutexattr_init Return Values
Destroying a Mutex Attribute Object
pthread_mutexattr_destroy Syntax
pthread_mutexattr_destroy Return Values
pthread_mutexattr_setpshared Syntax
pthread_mutexattr_setpshared Return Values
pthread_mutexattr_getpshared Syntax
pthread_mutexattr_getpshared Return Values
Setting the Mutex Type Attribute
pthread_mutexattr_settype Syntax
pthread_mutexattr_settype Return Values
Getting the Mutex Type Attribute
pthread_mutexattr_gettype Syntax
pthread_mutexattr_gettype Return Values
Setting the Mutex Attribute's Protocol
pthread_mutexattr_setprotocol Syntax
pthread_mutexattr_setprotocol Return Values
Getting the Mutex Attribute's Protocol
pthread_mutexattr_getprotocol Syntax
pthread_mutexattr_getprotocol Return Values
Setting the Mutex Attribute's Priority Ceiling
pthread_mutexattr_setprioceiling Syntax
pthread_mutexattr_setprioceiling Return Values
Getting the Mutex Attribute's Priority Ceiling
pthread_mutexattr_getprioceiling Syntax
pthread_mutexattr_getprioceiling Return Values
Setting the Mutex's Priority Ceiling
pthread_mutex_setprioceiling Syntax
pthread_mutex_setprioceiling Return Values
Getting the Mutex's Priority Ceiling
pthread_mutex_getprioceiling Syntax
pthread_mutex_getprioceiling Return Values
Setting the Mutex's Robust Attribute
pthread_mutexattr_setrobust_np Syntax
pthread_mutexattr_setrobust_np Return Values
Getting the Mutex's Robust Attribute
pthread_mutexattr_getrobust_np Syntax
pthread_mutexattr_getrobust_np Return Values
pthread_mutex_init Return Values
pthread_mutex_consistent_np Syntax
pthread_mutex_consistent_np Return Values
pthread_mutex_lock Return Values
pthread_mutex_unlock Return Values
Locking a Mutex Without Blocking
pthread_mutex_trylock Return Values
Locking a Mutex Before a Specified Absolute Time
pthread_mutex_timedlock() Syntax
pthread_mutex_timedlock() Return Values
Locking a Mutex Within a Specified Time Interval
pthread_mutex_reltimedlock_np() Syntax
pthread_mutex_reltimedlock_np() Return Values
pthread_mutex_destroy Return Values
Code Examples of Mutex Locking
Examples of Using Lock Hierarchies
pthread_spin_init() Return Values
pthread_spin_lock() Return Values
Acquiring a Non-Blocking Spin Lock
pthread_spin_trylock() Return Values
pthread_spin_unlock() Return Values
pthread_spin_destroy() Return Values
Initializing a Condition Variable Attribute
pthread_condattr_init Return Values
Removing a Condition Variable Attribute
pthread_condattr_destroy Syntax
pthread_condattr_destroy Return Values
Setting the Scope of a Condition Variable
pthread_condattr_setpshared Syntax
pthread_condattr_setpshared Return Values
Getting the Scope of a Condition Variable
pthread_condattr_getpshared Syntax
pthread_condattr_getpshared Return Values
Setting the Clock Selection Condition Variable
pthread_condattr_setclock Syntax
pthread_condattr_setclock Returns
Getting the Clock Selection Condition Variable
pthread_condattr_getclock Syntax
pthread_condattr_getclock Returns
Initializing a Condition Variable
pthread_cond_init Return Values
Blocking on a Condition Variable
pthread_cond_wait Return Values
pthread_cond_signal Return Values
Blocking Until a Specified Time
pthread_cond_timedwait Return Values
Blocking For a Specified Interval
pthread_cond_reltimedwait_np Syntax
pthread_cond_reltimedwait_np Return Values
pthread_cond_broadcast Return Values
Destroying the Condition Variable State
pthread_cond_destroy Return Values
Synchronization With Semaphores
Initializing Semaphores With Intraprocess Scope
Initializing Semaphores With Interprocess Scope
Decrementing a Semaphore Count
Destroying the Semaphore State
Producer and Consumer Problem Using Semaphores
Initializing a Read-Write Lock Attribute
pthread_rwlockattr_init Syntax
pthread_rwlockattr_init Return Values
Destroying a Read-Write Lock Attribute
pthread_rwlockattr_destroy Syntax
pthread_rwlockattr_destroy Return Values
Setting a Read-Write Lock Attribute
pthread_rwlockattr_setpshared Syntax
pthread_rwlockattr_setpshared Return Values
Getting a Read-Write Lock Attribute
pthread_rwlockattr_getpshared Syntax
pthread_rwlockattr_getpshared Return Values
Initializing a Read-Write Lock
pthread_rwlock_init Return Values
Acquiring the Read Lock on Read-Write Lock
pthread_rwlock_rdlock Return Values
Acquiring a Read Lock on a Read-Write Lock Before a Specified Absolute Time
pthread_rwlock_timedrdlock Syntax
pthread_rwlock_timedrdlock Return Values
Acquiring a Non-Blocking Read Lock on a Read-Write Lock
pthread_rwlock_tryrdlock Syntax
pthread_rwlock_tryrdlock Return Values
Acquiring the Write Lock on a Read-Write Lock
pthread_rwlock_wrlock Return Values
Acquiring a Non-blocking Write Lock on a Read-Write Lock
pthread_rwlock_trywrlock Syntax
pthread_rwlock_trywrlock Return Values
Acquiring a Write Lock on a Read-Write Lock Before a Specified Absolute Time
pthread_rwlock_timedwrlock Syntax
pthread_rwlock_timedwrlock Returns
pthread_rwlock_unlock Return Values
pthread_rwlock_destroy Return Values
Initializing a Synchronization Barrier
pthread_barrier_init() Return Values
Waiting for Threads to Synchronize at a Barrier
pthread_barrier_wait() Return Values
Destroying a Synchronization Barrier
pthread_barrier_destroy Syntax
pthread_barrier_destroy Return Values
Initializing a Barrier Attributes Object
pthread_barrierattr_init() Syntax
pthread_barrierattr_init() Return Values
Setting a Barrier Process-Shared Attribute
pthread_barrierattr_setpshared() Syntax
pthread_barrierattr_setpshared() Return Values
Getting a Barrier Process-Shared Attribute
pthread_barrierattr_getpshared() Syntax
pthread_barrierattr_getpshared() Return Values
Destroying a Barrier Attributes Object
pthread_barrierattr_destroy() Syntax
pthread_barrierattr_destroy() Return Values
Synchronization Across Process Boundaries
Producer and Consumer Problem Example
5. Programming With the Solaris Software
6. Programming With Solaris Threads
Table 4-3 lists the functions that manipulate mutex locks.
Table 4-3 Routines for Mutual Exclusion 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.
Note - For a mutex that is being initialized with the PTHREAD_MUTEX_ROBUST_NP attribute, the mutex memory must be cleared to zero before initialization.
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.
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_np() makes the mutex object, mutex, consistent after the death of its owner.
#include <pthread.h> int pthread_mutex_consistent_np(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_np() 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_np() for a mutex that is not inconsistent, or is not held, is undefined.
pthread_mutex_consistent_np() returns zero after completing successfully. Any other return value indicates that an error occurred.
pthread_mutex_consistent_np() 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_NP 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_ROBUST_NProbustness 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_np() 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_init() 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_np() is PTHREAD_MUTEX_ROBUST_NP, 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 4-1 shows some code fragments with mutex locking.
Example 4-1 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 4-1 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 4-2 shows possible deadlock scenarios.
Example 4-2 Deadlock
|
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 4-3 Conditional Locking
|
In Example 4-3, 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 4-4 and Example 4-5 show how to take three locks at once. Deadlock is prevented by taking the locks in a prescribed order.
Example 4-4 Singly-Linked List Structure
typedef 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 4-5 shows the C code to remove an item from a singly-linked list.
Example 4-5 Singly-Linked List With Nested Locking
node1_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 4-6 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 4-6 Circular-Linked List Structure
typedef 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 4-7 Circular Linked List With Nested Locking
void 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); }