Use the DECthreads global mutex when calling a library package that is not designed to run in a multithreaded environment. Unless the documentation for a library function specifically states that it is thread safe, assume that it is not compatible; in other words, assume it is nonreentrant.
The global mutex is one lock. Any code that calls any function that is not known to be reentrant uses the same lock. This prevents problems resulting from dependencies among threads that call library functions and those functions' calling other functions, and so on.
The global mutex is a recursive mutex. A thread that has locked the global mutex can relock it without deadlocking. The locking thread must call pthread_unlock_global_np() as many times as it called this routine, to allow another thread to lock the global mutex. Return Values If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows:
| Return | Description |
|---|---|
| 0 | Successful completion. |
Destroys the specified mutex attributes object.
C Binding #include <pthread.h>pthread_mutexattr_destroy(
attr );
Argument Data Type Access attr opaque pthread_mutexattr_t write
int
pthread_mutexattr_destroy (
pthread_mutexattr_t *attr);
attr
Mutex attributes object to be destroyed.
This routine destroys a mutex attributes object---that is, the object becomes uninitialized. Call this routine when your program no longer needs the specified mutex attributes object.Return Values If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows:After this routine is called, DECthreads may reclaim the storage used by the mutex attributes object. Mutexes that were created using this attributes object are not affected by the destruction of the mutex attributes object.
The results of calling this routine are unpredictable, if the attributes object specified in the attr argument does not exist.
| Return | Description |
|---|---|
| 0 | Successful completion. |
| [EINVAL] | The value specified by attr is invalid. |
Obtains the mutex type attribute in the specified mutex attribute object.
C Binding #include <pthread.h>pthread_mutexattr_gettype(
attr ,
type );
Argument Data Type Access attr opaque pthread_mutexattr_t read type integer write
int
pthread_mutexattr_gettype (
const pthread_mutexattr_t *attr,
int *type);
attr
Mutex attributes object whose mutex type attribute is obtained.type
Receives the value of the mutex type attribute. The type argument specifies the type of mutex that can be created. Valid values are:
- PTHREAD_MUTEX_NORMAL
- PTHREAD_MUTEX_DEFAULT (default)
- PTHREAD_MUTEX_RECURSIVE
- PTHREAD_MUTEX_ERRORCHECK
This routine obtains the value of the mutex type attribute in the mutex attributes object specified by the attr argument and stores it in the location specified by the type argument. See the pthread_mutexattr_settype() description for information about mutex types.Return Values On successful completion, this routine returns the mutex type in the location specified by the type argument.
If an error condition occurs, this routine returns an integer value indicating the type of the error. Possible return values are as follows:
| Return | Description |
|---|---|
| 0 | Successful completion. |
| [EINVAL] | The value specified by attr is invalid. |
Obtains the mutex type attribute in the specified mutex attribute object.
C Binding #include <pthread.h>pthread_mutexattr_gettype_np(
attr ,
type );
Argument Data Type Access attr opaque pthread_mutexattr_t read type integer write
int
pthread_mutexattr_gettype_np (
const pthread_mutexattr_t *attr,
int *type);
attr
Mutex attributes object whose mutex type attribute is obtained.type
Receives the value of the mutex type attribute. The type argument specifies the type of mutex that can be created. Valid values are:
- PTHREAD_MUTEX_NORMAL
- PTHREAD_MUTEX_DEFAULT (default)
- PTHREAD_MUTEX_RECURSIVE
- PTHREAD_MUTEX_ERRORCHECK
This routine obtains the value of the mutex type attribute in the mutex attributes object specified by the attr argument and stores it in the location specified by the type argument. See the pthread_mutexattr_settype() description for information about mutex types.Return Values On successful completion, this routine returns the mutex type attribute in the location specified by the type argument.
Note
This routine has been superseded by the pthread_mutexattr_gettype() routine, as specified by the Single UNIX Specification, Version 2.
If an error condition occurs, this routine returns an integer value indicating the type of the error. Possible return values are as follows:
| Return | Description |
|---|---|
| 0 | Successful completion. |
| [EINVAL] | The value specified by attr is invalid. |
Initializes a mutex attributes object.
C Binding #include <pthread.h>pthread_mutexattr_init(
attr );
Argument Data Type Access attr opaque pthread_mutexattr_t write
int
pthread_mutexattr_init (
pthread_mutexattr_t *attr);
attr
Address of the mutex attributes object to be initialized.
This routine initializes the mutex attributes object specified by the attr argument with a set of default values. A mutex attributes object is used to specify the attributes of one or more mutexes when they are created. The attributes object created by this routine is used only in calls to the pthread_mutex_init() routine.Return Values If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows:When a mutex attributes object is used to create a mutex, the values of the individual attributes determine the characteristics of the new mutex. Thus, attributes objects act as additional arguments to mutex creation. Changing individual attributes in an attributes object does not affect any mutexes that were previously created using that attributes object.
You can use the same mutex attributes object in successive calls to pthread_mutex_init(), from any thread. If multiple threads can change attributes in a shared mutex attributes object, your program must use a mutex to protect the integrity of the attributes object's contents.
Results are undefined if this routine is called and the attr argument specifies a mutex attributes object that is already initialized.
| Return | Description |
|---|---|
| 0 | Successful completion. |
| [ENOMEM] | Insufficient memory to create the mutex attributes object. |
Specifies the mutex type attribute that is used when a mutex is created.
C Binding #include <pthread.h>pthread_mutexattr_settype(
attr ,
type );
Argument Data Type Access attr opaque pthread_mutexattr_t write type integer read
int
pthread_mutexattr_settype (
pthread_mutexattr_t *attr,
int type);
attr
Mutex attributes object whose mutex type attribute is to be modified.type
New value for the mutex type attribute. The type argument specifies the type of mutex that will be created. Valid values are:
- PTHREAD_MUTEX_NORMAL
- PTHREAD_MUTEX_DEFAULT (default)
- PTHREAD_MUTEX_RECURSIVE
- PTHREAD_MUTEX_ERRORCHECK
This routine sets the mutex type attribute that is used to determine which type of mutex is created based on a subsequent call to pthread_mutex_init(). See Section 2.4.1 for information on the types of mutexes.Return Values If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows:
| Return | Description |
|---|---|
| 0 | Successful completion. |
| [EINVAL] | The value specified by attr or type is invalid. |
| [ESRCH] | The value specified by attr does not refer to an existing mutex attributes object. |
Specifies the mutex type attribute that is used when a mutex is created.
C Binding #include <pthread.h>pthread_mutexattr_settype_np(
attr ,
type );
Argument Data Type Access attr opaque pthread_mutexattr_t write type integer read
int
pthread_mutexattr_settype_np (
pthread_mutexattr_t *attr,
int type);
attr
Mutex attributes object whose mutex type attribute is to be modified.type
New value for the mutex type attribute. The type argument specifies the type of mutex that will be created. Valid values are:
- PTHREAD_MUTEX_NORMAL
- PTHREAD_MUTEX_DEFAULT (default)
- PTHREAD_MUTEX_RECURSIVE
- PTHREAD_MUTEX_ERRORCHECK
This routine sets the mutex type attribute that is used to determine which type of mutex is created based on a subsequent call to pthread_mutex_init(). See Section 2.4.1 for information on the types of mutexes.Return Values If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows:
Note
This routine has been superseded by the pthread_mutexattr_settype() routine, as specified by the Single UNIX Specification, Version 2.
| Return | Description |
|---|---|
| 0 | Successful completion. |
| [EINVAL] | The value specified by attr or type is invalid. |
| [ESRCH] | The value specified by attr does not refer to an existing mutex attributes object. |
Destroys a mutex.
C Binding #include <pthread.h>pthread_mutex_destroy(
mutex );
Argument Data Type Access mutex opaque pthread_mutex_t write
int
pthread_mutex_destroy (
pthread_mutex_t *mutex);
mutex
The mutex to be destroyed.
This routine destroys the specified mutex by uninitializing it, and should be called when a mutex object is no longer referenced. After this routine is called, DECthreads may reclaim internal storage used by the specified mutex.Return Values If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows:It is safe to destroy an initialized mutex that is unlocked. However, it is illegal to destroy a locked mutex.
The results of this routine are unpredictable if the mutex object specified in the mutex argument does not currently exist, or is not initialized.
| Return | Description |
|---|---|
| 0 | Successful completion. |
| [EBUSY] | An attempt was made to destroy the object referenced by mutex while it is locked or referenced. |
| [EINVAL] | The value specified by mutex is invalid. |
Obtains the object name from a mutex object.
C Binding #include <pthread.h>pthread_mutex_getname_np(
mutex ,
name ,
len );
Argument Data Type Access mutex opaque pthread_mutex_t read name char write len opaque size_t read
int
pthread_mutex_getname_np (
pthread_mutex_t *mutex,
char *name,
size_t len);
mutex
Address of the mutex object whose object name is to be obtained.name
Location to store the obtained object name.len
Length in bytes of buffer at the location specified by name.
This routine copies the object name from the mutex object specified by the mutex argument to the buffer at the location specified by the name argument. Before calling this routine, your program must allocate the buffer indicated by name.Return Values If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows:The object name is a C language string and provides an identifier that is meaningful to a person debugging a DECthreads-based multithreaded application. The maximum number of characters in the object name is 31.
If the specified condition variable object has not been previously set with an object name, this routine copies a C language null string into the buffer at location name.
| Return | Description |
|---|---|
| 0 | Successful completion. |
| [EINVAL] | The value specified by mutex is invalid. |
Initializes a mutex with attributes specified by the attr argument.
C Binding #include <pthread.h>pthread_mutex_init(
mutex ,
attr );
Argument Data Type Access mutex opaque pthread_mutex_t write attr opaque pthread_mutexattr_t read
int
pthread_mutex_init (
pthread_mutex_t *mutex,
const pthread_mutexattr_t *attr);
mutex
Mutex created.attr
Mutex attributes object to be used to initialize the characteristics of the created mutex.
This routine initializes a mutex with the attributes specified by the mutex attributes object specified in the attr argument. A mutex is a synchronization object that allows multiple threads to serialize their access to shared data.Return Values If an error condition occurs, this routine returns an integer value indicating the type of error, the mutex is not initialized, and the contents of mutex are undefined. Possible return values are as follows:The mutex is initialized and set to the unlocked state. If attr is set to NULL, the default mutex attributes are used. The pthread_mutexattr_settype() routine can be used to specify the type of mutex that is created (normal, recursive, or errorcheck).
See Chapter 2 for more information about mutex usage.
A mutex is a resource of the process, not part of any particular thread. A mutex is neither destroyed nor unlocked automatically when any thread exits. Because mutexes are shared, they may be allocated in heap or static memory, but not on a stack.
Use the PTHREAD_MUTEX_INITIALIZER macro to statically initialize a mutex without calling this routine. Statically initialized mutexes need not be destroyed using pthread_mutex_destroy(). Use this macro as follows:
pthread_mutex_t mutex = PTHREAD_MUTEX_INITIALIZEROnly normal mutexes can be statically initialized.
| Return | Description |
|---|---|
| 0 | Successful completion. |
| [EAGAIN] | The system lacks the necessary resources to initialize the mutex. |
| [ENOMEM] | Insufficient memory exists to initialize the mutex. |
| [EBUSY] | The implementation has detected an attempt to reinitialize the mutex (a previously initialized, but not yet destroyed mutex). |
| [EINVAL] | The value specified by mutex is invalid. |
| [EPERM] | The caller does not have privileges to perform this operation. |
Locks an unlocked mutex. If the mutex is already locked, the calling thread blocks until the mutex becomes available.
C Binding #include <pthread.h>pthread_mutex_lock(
mutex );
Argument Data Type Access mutex opaque pthread_mutex_t read
int
pthread_mutex_lock (
pthread_mutex_t *mutex);
mutex
Mutex to be locked.
This routine locks a mutex with behavior that depends upon the type of mutex, as follows:Return Values If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows:
- If a normal or default mutex is specified, a deadlock can result if the current owner of the mutex calls this routine in an attempt to lock the mutex a second time. (The deadlock is not detected or reported.)
- If a recursive mutex is specified, the current owner of the mutex can relock the same mutex without blocking. The lock count is incremented for each recursive lock within the thread.
- If an errorcheck mutex is specified and the current owner tries to lock the mutex a second time, this routine reports the [EDEADLK] error. If the mutex is locked by another thread, the calling thread waits for the mutex to become available.
Use the pthread_mutexattr_settype() routine to set the type of the mutex to normal, default, recursive, or errorcheck. For more information about mutexes, see Chapter 2.
The thread that has locked a mutex becomes its current owner and remains the owner until the same thread has unlocked it. This routine returns with the mutex in the locked state and with the calling thread as the mutex's current owner.
A recursive or errorcheck mutex records the identity of the thread that locks it, allowing debuggers to display this information. In most cases, normal and default mutexes do not record the owning thread's identity.
| Return | Description |
|---|---|
| 0 | Successful completion. |
| [EINVAL] |
The value specified by
mutex is invalid, or
The mutex was created with the protocol attribute set to PTHREAD_PRIO_PROTECT and the calling thread's priority set higher than the mutex's current priority ceiling. |
| [EDEADLK] | A deadlock condition is detected. |
Changes the object name in a mutex object.
C Binding #include <pthread.h>pthread_mutex_setname_np(
mutex ,
name ,
mbz );
Argument Data Type Access mutex opaque pthread_mutex_t write name char read mbz void read
int
pthread_mutex_setname_np (
pthread_mutex_t *mutex,
const char *name,
void *mbz);
mutex
Address of the mutex object whose object name is to be changed.name
Object name value to copy into the mutex object.mbz
(Must be zero) Argument for use by DECthreads.
This routine changes the object name in the mutex object specified by the mutex argument to the value specified by the name argument. To set a new mutex object's object name, call this routine immediately after initializing the mutex object.
Previous | Next | Contents