pthread_cond_timedwait() — Wait on a condition variable

Standards

Standards / Extensions	C or C++	Dependencies
POSIX.4a Single UNIX Specification, Version 3	both	POSIX(ON)

Format

#define _OPEN_THREADS
#include <pthread.h>

int pthread_cond_timedwait(pthread_cond_t *cond, pthread_mutex_t *mutex,
                           const struct timespec *abstime);

SUSV3:

#define _UNIX03_THREADS 
#include <pthread.h>
int pthread_cond_timedwait(pthread_cond_t * __restrict__cond,
                           pthread_mutex_t * __retrict__mutex,
                           const struct timespec * __restrict__abstime);

General description

Allows a thread to wait on a condition variable until satisfied or until a specified time occurs. pthread_cond_timedwait() is the same as pthread_cond_wait() except it returns an error if the absolute time, specified by abstime, satisfies one of these conditions:

Passes before cond is signaled or broadcasted
Has already been passed at the time of the call

When such timeouts occur, pthread_cond_timedwait() reacquires the mutex, referenced by mutex (created by pthread_mutex_init()).

The two elements within the struct timespec are defined as follows:

tv_sec: The time to wait for the condition signal. It is expressed in seconds from midnight, January 1, 1970 UTC. The value specified must be greater than or equal to current calendar time expressed in seconds since midnight, January 1, 1970 UTC and less than 2,147,483,648 seconds.
tv_nsec: The time in nanoseconds to be added to tv_sec to determine when to stop waiting. The value specified must be greater than or equal to zero (0) and less than 1,000,000,000 (1,000 million).

Returned value

If successful, pthread_cond_timedwait() returns 0.

If unsuccessful, pthread_cond_timedwait() returns -1 and sets errno to one of the following values:

Error Code

Description

EAGAIN

For a private condition variable, the time specified by abstime has passed.

EINVAL

Can be one of the following error conditions:

The value specified by cond is not valid.
The value specified by mutex is not valid.
The value specified by abstime (tv_sec) is not valid.
The value specified by abstime (tv_nsec) is not valid.
Different mutexes were specified for concurrent operations on the same condition variable.

ETIMEDOUT

For a shared condition variable, the time specified by abstime has passed.

Note: In SUSV3, pthread_cond_timedwait() also returns ETIMEDOUT for a private condition variable, when the time specified by abstime has passed.

EPERM

The mutex was not owned by the current thread at the time of the call.

Special behavior for Single UNIX Specification, Version 3: If unsuccessful, pthread_cond_timedwait() returns an error number to indicate the error.

Usage notes

If the condition variable is shared (PTHREAD_PROCESS_SHARED), the mutex must also be shared, with the _OPEN_SYS_MUTEX_EXT feature defined when the mutex was created and initialized.

If the condition variable is private (PTHREAD_PROCESS_PRIVATE), the mutex must also be private.

If the condition variable is shared, all calls to pthread_cond_wait() or pthread_cont_timedwait() for a given condition variable must use the same mutex for the life of the process, or until both the condition variable and mutex are destroyed (using pthread_cond-destroy() and pthread_mutex_destroy()).

Example

CELEBP21

⁄* CELEBP21 *⁄                                   
#define _OPEN_THREADS                                                           
#include <pthread.h>                                                            
#include <stdio.h>                                                              
#include <time.h>                                                               
#include <errno.h>                                                              
                                                                                
main() {                                                                        
  pthread_cond_t cond;                                                          
  pthread_mutex_t mutex;                                                        
  time_t T;                                                                     
  struct timespec t;                                                            
                                                                                
  if (pthread_mutex_init(&mutex, NULL) != 0) {                                  
    perror("pthread_mutex_init() error");                                       
    exit(1);                                                                    
  }                                                                             
                                                                                
  if (pthread_cond_init(&cond, NULL) != 0) {                                    
    perror("pthread_cond_init() error");                                        
    exit(2);                                                                    
  }                                                                             
                                                                                
  if (pthread_mutex_lock(&mutex) != 0) {                                        
    perror("pthread_mutex_lock() error");                                       
    exit(3);                                                                    
  }                                                                             
                                                                                
  time(&T);                                                                     
  t.tv_sec = T + 2;                                                             
  printf("starting timedwait at %s", ctime(&T));                                
  if (pthread_cond_timedwait(&cond, &mutex, &t) != 0)                           
    if (errno == EAGAIN)                                                        
      puts("wait timed out");                                                   
    else {                                                                      
      perror("pthread_cond_timedwait() error");                                 
      exit(4);                                                                  
    }                                                                           
                                                                                
  time(&T);                                                                     
  printf("timedwait over at %s", ctime(&T));                                    
}

Output:

starting timedwait at Fri Jun 16 10:44:00 2001
wait timed out
timedwait over at Fri Jun 16 10:44:02 2001