pthread_cond_init

Initializes a condition variable.

Syntax

pthread_cond_init( cond, attr );

Argument Data Type Access

cond opaque pthread_cond_t write attr opaque pthread_ read condattr_t

C Binding

#include 


int
pthread_cond_init (
         pthread_cond_t   *cond,
         const pthread_condattr_t   *attr);

Arguments

cond: Condition variable to initialize.
attr: Condition variable attributes object that defines the characteristics of the condition variable to initialize.

Description

This routine initializes a condition variable (cond) with attributes referenced by attr. If attr is NULL, the default condition variable attributes are used.

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.

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

The macro PTHREAD_COND_INITIALIZER can be used to initialize statically allocated condition variables to the default condition variable attributes. To call this macro, enter: pthread_cond_t condition = PTHREAD_COND_INITIALIZER

When statically initialized, a condition variable should not also be using pthread_cond_init. Also, a statically initialized condition variable need not be destroyed using pthread_cond_destroy.

Under certain circumstances it may be impossible to wait upon a statically initialized condition variable when the process virtual address space (or some other memory limit) is nearly exhausted. In such a case pthread_cond_wait or pthread_cond_timedwait may return ENOMEM. You can avoid this possibility by initializing critical condition variables with pthread_cond_init.

Return Values

If an error condition occurs, this routine returns an integer value indicating the type of error, the condition variable is not initialized, and the contents of cond are undefined. Possible return values are as follows:

Return Description

0 Successful completion. [EAGAIN] The system lacks the necessary resources to initialize another condition variable, or The system-imposed limit on the total number of condition variables under execution by a single user is exceeded. [EBUSY] The implementation has detected an attempt to reinitialize the object referenced by cond, a previously initialized, but not yet destroyed condition variable. [EINVAL] The value specified by attr is invalid. [ENOMEM] Insufficient memory exists to initialize the condition variable.

Associated Routines

   pthread_cond_broadcast
   pthread_cond_destroy
   pthread_cond_signal
   pthread_cond_timedwait
   pthread_cond_wait