Synopsis

#include <threads.h>

int condWait(handle_t h, handle_t m, time_t timeout);

Status

Implemented

Conformance

Phoenix-RTOS specific

Description

The condWait() function shall block on a condition variable specified by h. The application shall ensure that these functions are called with mutex m locked by the calling thread; otherwise, an error or undefined behavior results.

These functions atomically release mutex and cause the calling thread to block on the condition variable h; atomically here means "atomically with respect to access by another thread to the mutex m 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 condSignal() or condBroadcast() in that thread shall behave as if it were issued after the about-to-block thread has blocked.

Upon successful return, the mutex m shall have been locked and shall be owned by the calling thread.

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 condWait() functions may occur. Since the return from condWait() 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 the condWait() 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 condBroadcast() 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 may 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.

A thread that has been unblocked because it has been canceled while blocked in a call to condWait() 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.

If a signal is delivered to a thread waiting for a condition variable, upon return from the signal handler the thread resumes waiting for the condition variable as if it was not interrupted, or it shall return zero due to spurious wakeup.

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

Return value

Upon successful completion, a value of zero shall be returned; otherwise, an error number shall be returned to indicate the error.

Errors

This function shall fall if:

  • -EINVAL - The value h does not refer to an initialised condition variable,

  • -EINVAL - Parent process for h variable or mutex m ceased to exist during function call

Tests

Untested

Known bugs

None

See Also

  1. Standard library functions
  2. Table of Contents