Mutual Exclusion Lock Attributes

Use mutual exclusion locks (mutexes) to serialize thread execution. Mutual exclusion locks synchronize threads, usually by ensuring that only one thread at a time executes a critical section of code. Mutex locks can also preserve single-threaded code.

To change the default mutex attributes, you can declare and initialize an attribute object. Often, the mutex attributes are set in one place at the beginning of the application so they can be located quickly and modified easily. The following table lists the functions discussed in this section that manipulate mutex attributes.

Table 4-1 Mutex Attributes Routines

"Initialize a Mutex Attribute Object"	"pthread_mutexattr_init(3T)"
"Destroy a Mutex Attribute Object"	"pthread_mutexattr_destroy(3T)"
"Set the Scope of a Mutex "	"pthread_mutexattr_setpshared(3T)"
"Get the Scope of a Mutex "	"pthread_mutexattr_getpshared(3T)"

The differences between Solaris and POSIX, when defining the scope of a mutex, are shown in Table 4-2.

Table 4-2 Mutex Scope Comparison

Solaris	POSIX	Definition
USYNC_PROCESS	PTHREAD_PROCESS_SHARED	Use to synchronize threads in this and other processes
USYNC_THREAD	PTHREAD_PROCESS_PRIVATE	Use to synchronize threads in this process only

Initialize a Mutex Attribute Object

pthread_mutexattr_init(3T)

Use pthread_mutexattr_init() 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 pthread_mutexattr_destroy(3T). The pthread_mutexattr_init() call returns a pointer to an opaque object. If the object is not destroyed, a memory leak will result.

Return Values

Returns zero after completing successfully. Any other returned value indicates that an error occurred. If either of the following conditions occurs, the function fails and returns the corresponding value.

ENOMEM

There is not enough memory to initialize the thread attributes object.

EINVAL

The value specified by mattr is invalid.

Destroy a Mutex Attribute Object

pthread_mutexattr_destroy(3T)

pthread_mutexattr_destroy() 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 returned value indicates that an error occurred. If the following condition occurs, the function fails and returns the corresponding value.

EINVAL

The value specified by mattr is invalid.

Set the Scope of a Mutex

pthread_mutexattr_setpshared(3T)

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

Returns zero after completing successfully. Any other returned value indicates that an error occurred. If the following condition occurs, the function fails and returns the corresponding value.

EINVAL

The value specified by mattr is invalid.

Get the Scope of a Mutex

pthread_mutexattr_getpshared(3T)

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

Returns zero after completing successfully. Any other returned value indicates that an error occurred. If the following condition occurs, the function fails and returns the corresponding value.

EINVAL

The value specified by mattr is invalid.