Condition Variable Attributes

Use condition variables to atomically block threads until a particular condition is true. Always use condition variables together with a mutex lock.

With a condition variable, a thread can atomically block until a condition is satisfied. The condition is tested under the protection of a mutual exclusion lock (mutex).

When the condition is false, a thread usually blocks on a condition variable and atomically releases the mutex waiting for the condition to change. When another thread changes the condition, that thread can signal the associated condition variable to cause one or more waiting threads to perform the following actions:

• Wake up

• Acquire the mutex again

• Re-evaluate the condition

Condition variables can be used to synchronize threads among processes in the following situations:

• The threads are allocated in memory that can be written to

• The memory is shared by the cooperating processes

The scheduling policy determines how blocking threads are awakened. The default scheduling policy, SCHED_OTHER, does not specify the order in which threads are awakened. Under the SCHED_FIFO and SCHED_RR real-time scheduling policies, threads are awakened in priority order.

The attributes for condition variables must be set and initialized before the condition variables can be used. The functions that manipulate condition variable attributes are listed in Table 4–4.

Table 4–4 Condition Variable Attributes

Operation	Function Description
Initialize a condition variable attribute	pthread_condattr_init Syntax
Remove a condition variable attribute	pthread_condattr_destroy Syntax
Set the scope of a condition variable	pthread_condattr_setpshared Syntax
Get the scope of a condition variable	pthread_condattr_getpshared Syntax
Get the clock selection condition variable attribute	pthread_condattr_getclock Syntax
Set the clock selection condition variable attribute	pthread_condattr_setclock Syntax

Initializing a Condition Variable Attribute

Use pthread_condattr_init(3C) to initialize attributes that are associated with this object to their default values. Storage for each attribute object is allocated by the threads system during execution.

pthread_condattr_init Syntax

int pthread_condattr_init(pthread_condattr_t *cattr);

#include <pthread.h>
pthread_condattr_t cattr;
int ret;

/* initialize an attribute to default value */
ret = pthread_condattr_init(&cattr); 

The default value of the pshared attribute when this function is called is PTHREAD_PROCESS_PRIVATE. This value of pshared means that the initialized condition variable can be used within a process.

cattr is an opaque data type that contains a system-allocated attribute object. The possible values of cattr's scope are PTHREAD_PROCESS_PRIVATE and PTHREAD_PROCESS_SHARED . PTHREAD_PROCESS_PRIVATE is the default value.

Before a condition variable attribute can be reused, the attribute must first be reinitialized by pthread_condattr_destroy(3C). The pthread_condattr_init() call returns a pointer to an opaque object. If the object is not destroyed, a memory leak results.

pthread_condattr_init Return Values

pthread_condattr_init() returns zero after completing successfully. Any other return value indicates that an error occurred. When either of the following conditions occurs, the function fails and returns the corresponding value.

ENOMEM

Description:

Insufficient memory allocated to initialize the thread attributes object.

EINVAL

Description:

The value specified by cattr is invalid.

Removing a Condition Variable Attribute

Use pthread_condattr_destroy(3C) to remove storage and render the attribute object invalid.

pthread_condattr_destroy Syntax

int pthread_condattr_destroy(pthread_condattr_t *cattr);

#include <pthread.h>
pthread_condattr_t cattr;
int ret;

/* destroy an attribute */
ret
 = pthread_condattr_destroy(&cattr); 

pthread_condattr_destroy Return Values

pthread_condattr_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.

EINVAL

Description:

The value specified by cattr is invalid.

Setting the Scope of a Condition Variable

pthread_condattr_setpshared(3C) sets the scope of a condition variable to either process private (intraprocess) or system wide (interprocess).

pthread_condattr_setpshared Syntax

int pthread_condattr_setpshared(pthread_condattr_t *cattr, int pshared);

#include <pthread.h> 
pthread_condattr_t cattr; 
int ret; 

/* all processes */ 
ret = pthread_condattr_setpshared(&cattr, PTHREAD_PROCESS_SHARED); 

/* within a process */ 
ret = pthread_condattr_setpshared(&cattr, PTHREAD_PROCESS_PRIVATE);

A condition variable created with the pshared attribute set in shared memory to PTHREAD_PROCESS_SHARED, can be shared among threads from more than one process.

If the mutex pshared attribute is set to PTHREAD_PROCESS_PRIVATE, only those threads created by the same process can operate on the mutex. PTHREAD_PROCESS_PRIVATE is the default value. PTHREAD_PROCESS_PRIVATE behaves like a local condition variable. The behavior of PTHREAD_PROCESS_SHARED is equivalent to a global condition variable.

pthread_condattr_setpshared Return Values

pthread_condattr_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.

EINVAL

Description:

The value of cattr is invalid, or the pshared value is invalid.

Getting the Scope of a Condition Variable

pthread_condattr_getpshared(3C) gets the current value of pshared for the attribute object cattr.

pthread_condattr_getpshared Syntax

int pthread_condattr_getpshared(const pthread_condattr_t *restrict cattr,
          int *restrict pshared);

#include <pthread.h> 

pthread_condattr_t cattr; 
int pshared; 
int ret; 

/* get pshared value of condition variable */ 
ret = pthread_condattr_getpshared(&cattr, &pshared); 

The value of the attribute object is either PTHREAD_PROCESS_SHARED or PTHREAD_PROCESS_PRIVATE.

pthread_condattr_getpshared Return Values

pthread_condattr_getpshared() 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.

EINVAL

Description:

The value of cattr is invalid.

Setting the Clock Selection Condition Variable

Use the pthread_condattr_setclock(3C) function to set the clock attribute in an initialized attributes object referenced by attr. If pthread_condattr_setclock() is called with a clock_id argument that refers to a CPU-time clock, the call fails. The clock attribute is the clock ID of the clock that is used to measure the timeout service of pthread_cond_timedwait(). The default value of the clock attribute refers to the system clock, CLOCK_REALTIME. At this time, the only other possible value for the clock attribute is CLOCK_MONOTONIC.

pthread_condattr_setclock Syntax

int pthread_condattr_setclock(pthread_condattr_t attr, 
          clockid_t clock_id);

#include <pthread.h>

pthread_condattr_t attr
clockid_t clock_id
int ret


ret = pthread_condattr_setclock(&attr &clock_id

pthread_condattr_setclock Returns

pthread_condattr_setclock() 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.

EINVAL

Description:

The value specified by clock_id does not refer to a known clock, or is a CPU-time clock.

Getting the Clock Selection Condition Variable

Use the pthread_condattr_getclock(3C) function to obtain the value of the clock attribute from the attributes object referenced by attr. The clock attribute is the clock ID of the clock that is used to measure the timeout service of pthread_cond_timedwait().

pthread_condattr_getclock Syntax

int pthread_condattr_getclock(const pthread_condattr_t *restrict attr,
          clockid_t *restrict clock_id);

#include <pthread.h>

pthread_condattr_t attr
clockid_t clock_id
int ret


ret = pthread_condattr_getclock(&attr &clock_id

pthread_condattr_getclock Returns

pthread_condattr_getclock() returns zero after completing successfully and stores the value of the clock attribute of attr into the object referenced by the clock_id argument. Any other return value indicates that an error occurred. When the following condition occurs, the function fails and returns the corresponding value.

EINVAL

Description:

The value of attr is invalid.