pthread_cond_wait()

Wait on a condition variable

Synopsis:

#include <pthread.h>

int pthread_cond_wait( pthread_cond_t* cond,
                       pthread_mutex_t* mutex );

Arguments:

cond
A pointer to the pthread_cond_t object that you want the threads to block on.
mutex
The mutex that you want to unlock.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The pthread_cond_wait() function blocks the calling thread on the condition variable cond, and unlocks the associated mutex mutex. The calling thread must have locked mutex before waiting on the condition variable. On return from the function, the mutex is again locked and owned by the calling thread.

The calling thread is blocked until either another thread performs a signal or broadcast on the condition variable, a signal is delivered to the thread, or the thread is canceled (waiting on a condition variable is a cancellation point). In all cases, the thread reacquires the mutex before being unblocked.

If a thread that's blocked on a condition variable is canceled, the thread reacquires the mutex that's guarding the condition variable, so that the thread's cleanup handlers run in the same state as the critical code before and after the call to this function. If some other thread owns the lock, the canceled thread blocks until the mutex is available.

Note:
  • Don't use a recursive mutex with condition variables.
  • Make sure that the thread's cleanup handlers unlock the mutex.
  • This function can interfere with the kernel's efforts to manage power usage. For more information, see the Understanding the Microkernel's Concept of Time chapter of the QNX Neutrino Programmer's Guide.

Returns:

EOK
Success, or the call was interrupted by a signal.
EAGAIN
Insufficient system resources are available to wait on the condition.
EFAULT
A fault occurred trying to access the buffers provided.
EINVAL
One or more of the following is true:
  • One or more of cond or mutex is invalid.
  • Concurrent waits on cond used different mutexes.
  • The mutex has died; see SyncMutexEvent().
EPERM
The current thread doesn't own the mutex.

Examples:

Use condition variables to synchronize producer and consumer threads:

#include <stdio.h>
#include <pthread.h>

pthread_mutex_t mutex = PTHREAD_MUTEX_INITIALIZER;
pthread_cond_t cond = PTHREAD_COND_INITIALIZER;
int condition = 0;
int count = 0;

int consume( void )
{
   while( 1 )
   {
      pthread_mutex_lock( &mutex );
      while( condition == 0 )
         pthread_cond_wait( &cond, &mutex );
      printf( "Consumed %d\n", count );
      condition = 0;
      pthread_cond_signal( &cond );      
      pthread_mutex_unlock( &mutex );
   }

   return( 0 );
}

void*  produce( void * arg )
{
   while( 1 )
   {
      pthread_mutex_lock( &mutex );
      while( condition == 1 )
         pthread_cond_wait( &cond, &mutex );
      printf( "Produced %d\n", count++ );
      condition = 1;
      pthread_cond_signal( &cond );      
      pthread_mutex_unlock( &mutex );
   }
   return( 0 );
}

int main( void )
{
   pthread_create( NULL, NULL, &produce, NULL );
   return consume();
}

Classification:

POSIX 1003.1

Safety:  
Cancellation point Yes
Interrupt handler No
Signal handler Yes
Thread Yes