pthread_cond_wait(3) - NetBSD Manual Pages

PTHREAD_COND_WAIT(3)    NetBSD Library Functions Manual   PTHREAD_COND_WAIT(3)


NAME

     pthread_cond_wait, pthread_cond_timedwait -- wait on a condition variable


LIBRARY

     POSIX Threads Library (libpthread, -lpthread)


SYNOPSIS

     #include <pthread.h>

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

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


DESCRIPTION

     The pthread_cond_wait() function atomically blocks the current thread
     waiting on the condition variable specified by cond, and unblocks the
     mutex specified by mutex.  The waiting thread unblocks after another
     thread calls pthread_cond_signal(3), or pthread_cond_broadcast(3) with
     the same condition variable.  The current thread holds the lock on mutex
     upon return from the pthread_cond_wait call.

     The pthread_cond_timedwait() function atomically blocks the current
     thread waiting on the condition variable specified by cond, and unblocks
     the mutex specified by mutex.  The waiting thread unblocks after another
     thread calls pthread_cond_signal(3), or pthread_cond_broadcast(3) with
     the same condition variable, or if the system time reaches the time spec-
     ified in abstime.

     Note that a call to pthread_cond_wait() or pthread_cond_timedwait() may
     wake up spontaneously, without a call to pthread_cond_signal(3) or
     pthread_cond_broadcast(3).  The caller should prepare for this by invok-
     ing pthread_cond_wait() or pthread_cond_timedwait() within a predicate
     loop that tests whether the thread should proceed.

     When calling pthread_cond_wait() or pthread_cond_timedwait(), a temporary
     binding is established between the condition variable cond and the mutex
     mutex.

     The same mutex must be held while calling pthread_cond_broadcast() and
     pthread_cond_signal() on cond.  Additionally, the same mutex must be used
     for concurrent calls to pthread_cond_wait() and pthread_cond_timedwait().
     Only when a condition variable is known to be quiescent may an applica-
     tion change the mutex associated with it.  In this implementation, none
     of the functions enforce this requirement, but if the mutex is not held
     or independent mutexes are used the resulting behaviour is undefined.


RETURN VALUES

     If successful, the pthread_cond_wait() and pthread_cond_timedwait() func-
     tions will return zero.  Otherwise an error number will be returned to
     indicate the error.


ERRORS

     pthread_cond_wait() may fail if:

     [EINVAL]           The value specified by cond or the value specified by
                        mutex is invalid.

     pthread_cond_timedwait() shall fail if:

     [ETIMEDOUT]        The system time has reached or exceeded the time spec-
                        ified in abstime.

     pthread_cond_timedwait() may fail if:

     [EINVAL]           The value specified by cond, mutex, or abstime is
                        invalid.


SEE ALSO

     pthread_cond_broadcast(3), pthread_cond_destroy(3), pthread_cond_init(3),
     pthread_cond_signal(3)


STANDARDS

     pthread_cond_wait() and pthread_cond_timedwait() conform to ISO/IEC
     9945-1:1996 (``POSIX.1'').

NetBSD 5.0.1                     May 26, 2008                     NetBSD 5.0.1