cma_cond_create

Creates a condition variable.

Syntax

cma_cond_create( new_condition, attr);

Argument Data Type Access

new_condition opaque cma_t_cond write attr opaque cma_t_attr read

C Binding

#include 


void
cma_cond_create (
         cma_t_cond   *new_condition,
         cma_t_attr   *attr);

Arguments

new_condition: Variable that receives the handle for the new condition variable.
attr: Handle of the attributes object that defines the characteristics of the condition variable being created.

Description

This routine creates and initializes a condition variable. A condition variable is a synchronization object used in conjunction with a mutex. A mutex controls access to shared data; a condition variable allows threads to wait for that data to enter a defined state. The state is defined by a predicate.

A condition variable can be signaled or broadcasted to indicate that a predicate might have become true. The broadcast routine indicates that all waiting threads should resume and reevaluate the predicate. The signal routine can be used in the special case where only one waiting thread can continue.

If a thread that holds a mutex determines that the shared data is not in the correct state for it to proceed (the associated predicate is not true), it can wait on a condition variable associated with the desired state. Waiting on the condition variable automatically releases the mutex so that other threads can modify or examine the shared data. When a thread modifies the state of the shared data so that a predicate might be true, it signals or broadcasts on the appropriate condition variable so that threads waiting for that predicate can continue.

It is important that all threads waiting on a particular condition variable at any time hold the same mutex. At any time, an arbitrary number of condition variables can be associated with a single mutex, each representing a different predicate of the shared data protected by that mutex.

Condition variables are not owned by a particular thread. Any associated storage is not automatically deallocated when the creating thread terminates.

Exceptions

cma_e_existence
cma_e_use_error