NAME
pthread_cond_init - Creates a condition variable
SYNOPSIS
#include <pthread.h>
int pthread_cond_init( pthread_cond_t *cond,
pthread_condattr_t attr );
PARAMETERS
cond Condition variable that is created.
attr Condition variable attributes object that
defines the characteristics of the condition
variable created. If you specify
pthread_condattr_default, default attributes
are used.
DESCRIPTION
The pthread_cond_init() routine creates and initializes a condition
variable. A condition variable is a synchronization object used in con-
junction with a mutex. A mutex controls access to shared data; a condi-
tion variable allows threads to wait for that data to enter a defined
state. The state is defined by a Boolean expression called a predicate.
A condition variable is signaled or broadcast to indicate that a predi-
cate might have become true. The broadcast operation indicates that all
waiting threads need to resume and reevaluate the predicate. The signal
operation is used when any 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 waits 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 vari-
able at any time hold the same mutex. If they do not, the behavior of
the wait operation is unpredictable (an implementation can use the mutex
to control internal access to the condition variable object). However,
it is legal for a client to store condition variables and mutexes and
later reuse them in different combinations. The client must ensure that
no threads use the condition variable with the old mutex. At any time,
an arbitrary number of condition variables can be associated with a sin-
gle 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 ter-
minates.
RETURN VALUES
If the function fails, errno may be set to one of the following values:
Return Error Description
__________________________________________________
0 Successful completion.
-1 [EAGAIN] The system lacks the necessary resources
to initialize another condition variable.
-1 [EINVAL] Invalid attributes object.
-1 [ENOMEM] Insufficient memory exists to initialize
the condition variable.
RELATED INFORMATION
FUNCTIONS: pthread_cond_broadcast
pthread_cond_destroy
pthread_cond_signal
pthread_cond_timedwait
pthread_cond_wait