NAME

cnd_broadcast, cnd_signal — broadcast or signal a condition

SYNOPSIS

#include <threads.h>

int cnd_broadcast(cnd_t *cond);
int cnd_signal(cnd_t *cond);


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_broadcast() function shall, ^[CX]  as a single atomic operation,  determine which threads, if any, are blocked on the condition variable pointed to by cond and unblock all of these threads.

The cnd_signal() function shall, ^[CX]  as a single atomic operation,  determine which threads, if any, are blocked on the condition variable pointed to by cond and unblock at least one of these threads.

If these functions determine that there are no threads blocked on the condition variable pointed to by cond, they shall have no effect and shall return thrd_success.

^[CX] If more than one thread is blocked on a condition variable, the scheduling policy shall determine the order in which threads are unblocked. When each thread unblocked as a result of a cnd_broadcast() or cnd_signal() returns from its call to cnd_wait() or cnd_timedwait(), the thread shall own the mutex with which it called cnd_wait() or cnd_timedwait(). The thread(s) that are unblocked shall contend for the mutex according to the scheduling policy (if applicable), and as if each had called mtx_lock().

The cnd_broadcast() and cnd_signal() functions can be called by a thread whether or not it currently owns the mutex that threads calling cnd_wait() or cnd_timedwait() have associated with the condition variable during their waits; however, if predictable scheduling behavior is required, then that mutex shall be locked by the thread calling cnd_broadcast() or cnd_signal().

These functions shall not be affected if the calling thread executes a signal handler during the call.

The behavior is undefined if the value specified by the cond argument to cnd_broadcast() or cnd_signal() does not refer to an initialized condition variable.

RETURN VALUE

These functions shall return thrd_success on success, or thrd_error if the request could not be honored.

ERRORS

No errors are defined.

EXAMPLES

None.

APPLICATION USAGE

See the APPLICATION USAGE section for pthread_cond_broadcast(), substituting cnd_broadcast() for pthread_cond_broadcast() and cnd_signal() for pthread_cond_signal().

RATIONALE

As for pthread_cond_broadcast() and pthread_cond_signal(), spurious wakeups may occur with cnd_broadcast() and cnd_signal(), necessitating that applications code a predicate-testing-loop around the condition wait. (See the RATIONALE section for pthread_cond_broadcast().)

These functions are not affected by signal handlers for the reasons stated in XRAT B.2.3 Error Numbers .

FUTURE DIRECTIONS

None.

SEE ALSO

cnd_destroy , cnd_timedwait , pthread_cond_broadcast

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.