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