Initialize a Mutex Attribute Object
pthread_mutexattr_init(3THR)
Use pthread_mutexattr_init(3THR) to initialize attributes associated with this object to their default values. Storage for each attribute object is allocated by the threads system during execution.
The default value of the pshared attribute when this function is called is PTHREAD_PROCESS_PRIVATE, which means that the initialized mutex can be used within a process.
Prototype: int pthread_mutexattr_init(pthread_mutexattr_t *mattr); |
#include <pthread.h> pthread_mutexattr_t mattr; int ret; /* initialize an attribute to default value */ ret = pthread_mutexattr_init(&mattr); |
mattr is an opaque type that contains a system-allocated attribute object. The possible values of mattr's scope are PTHREAD_PROCESS_PRIVATE (the default) and PTHREAD_PROCESS_SHARED.
Before a mutex attribute object can be reinitialized, it must first be destroyed by a call to pthread_mutexattr_destroy(3THR). The pthread_mutexattr_init() call results in the allocation of an opaque object. If the object is not destroyed, a memory leak will result.
Return Values
pthread_mutexattr_init() returns zero after completing successfully. Any other return value indicates that an error occurred. If either of the following conditions occurs, the function fails and returns the corresponding value.
There is not enough memory to initialize the mutex attributes object.
Destroy a Mutex Attribute Object
pthread_mutexattr_destroy(3THR)
pthread_mutexattr_destroy(3THR) deallocates the storage space used to maintain the attribute object created by pthread_mutexattr_init().
Prototype: int pthread_mutexattr_destroy(pthread_mutexattr_t *mattr) |
#include <pthread.h> pthread_mutexattr_t mattr; int ret; /* destroy an attribute */ ret = pthread_mutexattr_destroy(&mattr); |
Return Values
pthread_mutexattr_destroy() returns zero after completing successfully. Any other return value indicates that an error occurred. If the following condition occurs, the function fails and returns the corresponding value.
The value specified by mattr is invalid.
Set the Scope of a Mutex
pthread_mutexattr_setpshared(3THR)
pthread_mutexattr_setpshared(3THR) sets the scope of the mutex variable.
The scope of a mutex variable can be either process private (intraprocess) or system wide (interprocess). If the mutex is created with the pshared attribute set to the PTHREAD_PROCESS_SHARED state, and it exists in shared memory, it can be shared among threads from more than one process. This is equivalent to the USYNC_PROCESS flag in mutex_init() in the original Solaris threads.
Prototype:
int pthread_mutexattr_setpshared(pthread_mutexattr_t *mattr,
int pshared);
|
#include <pthread.h>
pthread_mutexattr_t mattr;
int ret;
ret = pthread_mutexattr_init(&mattr);
/*
* resetting to its default value: private
*/
ret = pthread_mutexattr_setpshared(&mattr,
PTHREAD_PROCESS_PRIVATE);
|
If the mutex pshared attribute is set to PTHREAD_PROCESS_PRIVATE, only those threads created by the same process can operate on the mutex.
Return Values
pthread_mutexattr_setpshared() returns zero after completing successfully. Any other return value indicates that an error occurred. If the following condition occurs, the function fails and returns the corresponding value.
The value specified by mattr is invalid.
Get the Scope of a Mutex
pthread_mutexattr_getpshared(3THR)
pthread_mutexattr_getpshared(3THR) returns the scope of the mutex variable defined by pthread_mutexattr_setpshared().
Prototype:
int pthread_mutexattr_getpshared(pthread_mutexattr_t *mattr,
int *pshared);
|
#include <pthread.h> pthread_mutexattr_t mattr; int pshared, ret; /* get pshared of mutex */ ret = pthread_mutexattr_getpshared(&mattr, &pshared); |
Get the current value of pshared for the attribute object mattr. It is either PTHREAD_PROCESS_SHARED or PTHREAD_PROCESS_PRIVATE.
Return Values
pthread_mutexattr_getpshared() returns zero after completing successfully. Any other return value indicates that an error occurred. If the following condition occurs, the function fails and returns the corresponding value.
The value specified by mattr is invalid.
Set the Mutex Type Attribute
pthread_mutexattr_settype(3THR)
#include <pthread.h> int pthread_mutexattr_settype(pthread_mutexattr_t *attr , int type); |
pthread_mutexattr_settype(3THR) sets the mutex type attribute. The default value of the type attribute is PTHREAD_MUTEX_DEFAULT.
The type argument specifies the type of mutex. Valid mutex types include:
PTHREAD_MUTEX_NORMAL
This type of mutex does not detect deadlock. A thread attempting to relock this mutex without first unlocking it will deadlock. Attempting to unlock a mutex locked by a different thread results in undefined behavior. Attempting to unlock an unlocked mutex results in undefined behavior.
PTHREAD_MUTEX_ERRORCHECK
This type of mutex provides error checking. A thread attempting to relock this mutex without first unlocking it will return with an error. A thread attempting to unlock a mutex which another thread has locked will return with an error. A thread attempting to unlock an unlocked mutex will return with an error.
PTHREAD_MUTEX_RECURSIVE
A thread attempting to relock this mutex without first unlocking it will succeed in locking the mutex. The relocking deadlock which can occur with mutexes of type PTHREAD_MUTEX_NORMAL cannot occur with this type of mutex. Multiple locks of this mutex require the same number of unlocks to release the mutex before another thread can acquire the mutex. A thread attempting to unlock a mutex which another thread has locked will return with an error. A thread attempting to unlock an unlocked mutex will return with an error.
PTHREAD_MUTEX_DEFAULT
Attempting to recursively lock a mutex of this type results in undefined behavior. Attempting to unlock a mutex of this type which was not locked by the calling thread results in undefined behavior. Attempting to unlock a mutex of this type which is not locked results in undefined behavior. An implementation is allowed to map this mutex to one of the other mutex types. (For Solaris threads, PTHREAD_PROCESS_DEFAULT is mapped to PTHREAD_PROCESS_NORMAL.)
Return Values
If successful, the pthread_mutexattr_settype function returns zero. Otherwise, an error number is returned to indicate the error.
EINVAL
The value type is invalid.
EINVAL
The value specified by attr is invalid.
Get the Mutex Type Attribute
pthread_mutexattr_gettype(3THR)
#include <pthread.h> int pthread_mutexattr_gettype(pthread_mutexattr_t *attr , int *type); |
pthread_mutexattr_gettype(3THR) gets the mutex type attribute set by pthread_mutexattr_settype(). The default value of the type attribute is PTHREAD_MUTEX_DEFAULT.
The type argument specifies the type of mutex. Valid mutex types include:
PTHREAD_MUTEX_NORMAL
PTHREAD_MUTEX_ERRORCHECK
PTHREAD_MUTEX_RECURSIVE
PTHREAD_MUTEX_DEFAULT
For a description of each type, see "pthread_mutexattr_settype(3THR)".