pthread_cond_broadcast()--Broadcast Condition to All Waiting Threads

 #include <pthread.h>
 int pthread_cond_broadcast(pthread_cond_t *cond); 

The pthread_cond_broadcast() function wakes up all threads that are currently waiting on the condition variable specified by cond. If no threads are currently blocked on the condition variable, this call has no effect.

When the threads that were the target of the broadcast wake up, they contend for the mutex that they have associated with the condition variable on the call to pthread_cond_timedwait() or pthread_cond_wait().

The signal and broadcast functions can be called by a thread whether or not it currently owns the mutex associated with the condition variable. If predictable scheduling behavior is required from the applications viewpoint however, the mutex should be locked by the thread calling pthread_cond_signal() or pthread_cond_broadcast().

Note: For dependable use of condition variables, and to ensure that you do not lose wake up operations on condition variables, your application should always use a boolean predicate and a mutex with the condition variable.

Authorities and Locks

None.

Parameters

cond

(Input) Pointer to the condition variable that is to be broadcast to

Return Value

0

pthread_cond_broadcast() was successful. 

value

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

Error Conditions

If pthread_cond_broadcast() 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_init()--Initialize 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

See Code disclaimer information for information pertaining to code examples.

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

/* For safe condition variable usage, must use a boolean predicate and  */
/* a mutex with the condition.                                          */
int                 conditionMet = 0;
pthread_cond_t      cond  = PTHREAD_COND_INITIALIZER;
pthread_mutex_t     mutex = PTHREAD_MUTEX_INITIALIZER;

#define NTHREADS    5

void *threadfunc(void *parm)
{
  int           rc;

  rc = pthread_mutex_lock(&mutex);
  checkResults("pthread_mutex_lock()\n", rc);

  while (!conditionMet) {
    printf("Thread blocked\n");
    rc = pthread_cond_wait(&cond, &mutex);
    checkResults("pthread_cond_wait()\n", rc);
  }

  rc = pthread_mutex_unlock(&mutex);
  checkResults("pthread_mutex_lock()\n", rc);
  return NULL;
}

int main(int argc, char **argv)
{
  int                   rc=0;
  int                   i;
  pthread_t             threadid[NTHREADS];

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

  printf("Create %d threads\n", NTHREADS);
  for(i=0; i<NTHREADS; ++i) {
    rc = pthread_create(&threadid[i], NULL, threadfunc, NULL);
    checkResults("pthread_create()\n", rc);
  }

  sleep(5);  /* Sleep is not a very robust way to serialize threads */
  rc = pthread_mutex_lock(&mutex);
  checkResults("pthread_mutex_lock()\n", rc);

  /* The condition has occured. Set the flag and wake up any waiting threads */
  conditionMet = 1;
  printf("Wake up all waiting threads...\n");
  rc = pthread_cond_broadcast(&cond);
  checkResults("pthread_cond_broadcast()\n", rc);

  rc = pthread_mutex_unlock(&mutex);
  checkResults("pthread_mutex_unlock()\n", rc);

  printf("Wait for threads and cleanup\n");
  for (i=0; i<NTHREADS; ++i) {
    rc = pthread_join(threadid[i], NULL);
    checkResults("pthread_join()\n", rc);
  }
  pthread_cond_destroy(&cond);
  pthread_mutex_destroy(&mutex);

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

Output:

Entering testcase
Create 5 threads
Thread blocked
Thread blocked
Thread blocked
Thread blocked
Thread blocked
Wake up all waiting threads...
Wait for threads and cleanup
Main completed