NAME

cnd_timedwait, cnd_wait — wait on a condition

SYNOPSIS

#include <threads.h>

int cnd_timedwait(cnd_t * restrict cond, mtx_t * restrict mtx,
       const struct timespec * restrict ts);
int cnd_wait(cnd_t *cond, mtx_t *mtx);


DESCRIPTION

^[CX] The functionality described on this reference page is aligned with the ISO C standard. Any conflict between the requirements described here and the ISO C standard is unintentional. This volume of POSIX.1-2024 defers to the ISO C standard.

The cnd_timedwait() function shall atomically unlock the mutex pointed to by mtx and block until the condition variable pointed to by cond is signaled by a call to cnd_signal() or to cnd_broadcast(), or until after the TIME_UTC-based calendar time pointed to by ts, or until it is unblocked due to an unspecified reason.

The cnd_wait() function shall atomically unlock the mutex pointed to by mtx and block until the condition variable pointed to by cond is signaled by a call to cnd_signal() or to cnd_broadcast(), or until it is unblocked due to an unspecified reason.

^[CX] Atomically here means "atomically with respect to access by another thread to the mutex and then the condition variable". That is, if another thread is able to acquire the mutex after the about-to-block thread has released it, then a subsequent call to cnd_broadcast() or cnd_signal() in that thread shall behave as if it were issued after the about-to-block thread has blocked.

When the calling thread becomes unblocked, these functions shall lock the mutex pointed to by mtx before they return. The application shall ensure that the mutex pointed to by mtx is locked by the calling thread before it calls these functions.

When using condition variables there is always a Boolean predicate involving shared variables associated with each condition wait that is true if the thread should proceed. Spurious wakeups from the cnd_timedwait() and cnd_wait() functions may occur. Since the return from cnd_timedwait() or cnd_wait() does not imply anything about the value of this predicate, the predicate should be re-evaluated upon such return.

When a thread waits on a condition variable, having specified a particular mutex to either the cnd_timedwait() or the cnd_wait() operation, a dynamic binding is formed between that mutex and condition variable that remains in effect as long as at least one thread is blocked on the condition variable. During this time, the effect of an attempt by any thread to wait on that condition variable using a different mutex is undefined. Once all waiting threads have been unblocked (as by the cnd_broadcast() operation), the next wait operation on that condition variable shall form a new dynamic binding with the mutex specified by that wait operation. Even though the dynamic binding between condition variable and mutex might be removed or replaced between the time a thread is unblocked from a wait on the condition variable and the time that it returns to the caller or begins cancellation cleanup, the unblocked thread shall always re-acquire the mutex specified in the condition wait operation call from which it is returning.

^[CX] A condition wait (whether timed or not) is a cancellation point. When the cancelability type of a thread is set to PTHREAD_CANCEL_DEFERRED, a side-effect of acting upon a cancellation request while in a condition wait is that the mutex is (in effect) re-acquired before calling the first cancellation cleanup handler. The effect is as if the thread were unblocked, allowed to execute up to the point of returning from the call to cnd_timedwait() or cnd_wait(), but at that point notices the cancellation request and instead of returning to the caller of cnd_timedwait() or cnd_wait(), starts the thread cancellation activities, which includes calling cancellation cleanup handlers.

A thread that has been unblocked because it has been canceled while blocked in a call to cnd_timedwait() or cnd_wait() shall not consume any condition signal that may be directed concurrently at the condition variable if there are other threads blocked on the condition variable.

When cnd_timedwait() times out, it shall nonetheless release and re-acquire the mutex referenced by mtx, and may consume a condition signal directed concurrently at the condition variable.

^[CX] These functions shall not be affected if the calling thread executes a signal handler during the call, except that if a signal is delivered to a thread waiting for a condition variable, upon return from the signal handler either the thread shall resume waiting for the condition variable as if it was not interrupted, or it shall return thrd_success due to spurious wakeup.

The behavior is undefined if the value specified by the cond or mtx argument to these functions does not refer to an initialized condition variable or an initialized mutex object, respectively.

RETURN VALUE

The cnd_timedwait() function shall return thrd_success upon success, or thrd_timedout if the time specified in the call was reached without acquiring the requested resource, or thrd_error if the request could not be honored.

The cnd_wait() function shall return thrd_success upon success or thrd_error if the request could not be honored.

ERRORS

See RETURN VALUE.

EXAMPLES

None.

APPLICATION USAGE

None.

RATIONALE

These functions are not affected by signal handlers (except as stated in the DESCRIPTION) for the reasons stated in XRAT B.2.3 Error Numbers.

FUTURE DIRECTIONS

None.

SEE ALSO

cnd_broadcast, cnd_destroy, timespec_get

XBD 4.15.2 Memory Synchronization, <threads.h>

CHANGE HISTORY

First released in Issue 8. Included for alignment with the ISO/IEC 9899:2018 standard.