pthread_cond_init()--Initialize Condition Variable

 #include <pthread.h>
 int pthread_cond_init(pthread_cond_t *cond,
                       const pthread_condattr_t *attr);
                       pthread_cond_t  cond = PTHREAD_COND_INITIALIZER;   

The pthread_cond_init() function initializes a condition variable object with the specified attributes for use. The new condition may be used immediately for serializing threads. If attr is specified as NULL, all attributes are set to the default condition attributes for the newly created condition.

With these declarations and initialization:

pthread_cond_t       cond2;
pthread_cond_t       cond3;
pthread_condattr_t   attr;
pthread_condattr_init(&attr);

The following four condition variable initialization mechanisms have equivalent function:

pthread_cond_t       cond1 = PTHREAD_MUTEX_INITIALIZER;
pthread_cond_init(&cond2, NULL);
pthread_cond_init(&cond3, &attr);

All four condition variables are created with the default condition attributes.

Every condition variable must eventually be destroyed with pthread_cond_destroy().

Once a condition variable is created, it cannot be validly copied or moved to a new location. If the condition variable is copied or moved to a new location, the new object is not valid and cannot be used. Attempts to use the new object cause the EINVAL error.

Static initialization using the PTHREAD_COND_INITIALIZER does not immediately initialize the mutex. Instead, on first use, the functions pthread_cond_wait(), pthread_cond_timedwait(), pthread_cond_signal(), and pthread_cond_broadcast() branch into a slow path and cause the initialization of the condition. Due to this delayed initialization, the results of calling pthread_cond_destroy() on a condition variable that was initialized using static initialization and not used yet cause pthread_cond_destroy() to fail with the EINVAL error.

Authorities and Locks

None.

Parameters

cond

(Output) The address of the condition variable to initialize

attr

(Input) The address of the condition attributes object to use for initialization

Return Value

0

pthread_cond_init() was successful.

value

pthread_cond_init() was not successful. value is set to indicate the error condition.

Error Conditions

If pthread_cond_init() was not successful, the error condition returned usually indicates one of the following errors. Under some conditions, the value returned could indicate an error other than those listed here.

[EINVAL]

The value specified for the argument is not correct.

Related Information

• The <pthread.h> header file. See Header files for Pthread functions.
  
  
• pthread_cond_broadcast()--Broadcast Condition to All Waiting Threads
  
  
• pthread_cond_destroy()--Destroy Condition Variable
  
  
• pthread_cond_signal()--Signal Condition to One Waiting Thread
  
  
• pthread_cond_timedwait()--Timed Wait for Condition
  
  
• pthread_cond_wait()--Wait for Condition

Example

Note: By using the code examples, you agree to the terms of the Code license and disclaimer information.

#define _MULTI_THREADED
#include <pthread.h>
#include <stdio.h>
#include "check.h"

pthread_cond_t      cond1 = PTHREAD_COND_INITIALIZER;
pthread_cond_t      cond2;
pthread_cond_t      cond3;

int main(int argc, char **argv)
{
  int                   rc=0;
  pthread_condattr_t    attr;

  printf("Enter Testcase - %s\n", argv[0]);

  printf("Create the default cond attributes object\n");
  rc = pthread_condattr_init(&attr);
  checkResults("pthread_condattr_init()\n", rc);

  printf("Create the all of the default conditions in different ways\n");
  rc = pthread_cond_init(&cond2, NULL);
  checkResults("pthread_cond_init()\n", rc);

  rc = pthread_cond_init(&cond3, &attr);
  checkResults("pthread_cond_init()\n", rc);

  printf("- At this point, the conditions with default attributes\n");
  printf("- Can be used from any threads that want to use them\n");

  printf("Cleanup\n");
  pthread_condattr_destroy(&attr);
  pthread_cond_destroy(&cond1);
  pthread_cond_destroy(&cond2);
  pthread_cond_destroy(&cond3);

  printf("Main completed\n");
  return 0;
}

Output:

Enter Testcase - QP0WTEST/TPCOI0
Create the default cond attributes object
Create the all of the default conditions in different ways
- At this point, the conditions with default attributes
- Can be used from any threads that want to use them
Cleanup
Main completed

[ Back to top | Pthread APIs | APIs by category ]