SyncCondvarWait(), SyncCondvarWait_r()

Block a thread on a synchronization object

Synopsis:

#include <sys/neutrino.h>

int SyncCondvarWait( sync_t * sync,
                     sync_t * mutex );

int SyncCondvarWait_r( sync_t * sync,
                       sync_t * mutex );

Description:

The SyncCondvarWait() and SyncCondvarWait_r() functions are identical except in the way they indicate errors. See the Returns section for details.

These kernel calls block the calling thread on the synchronization object sync. If more than one thread is blocked on the object they're queued in priority order.

The mutex passed as the second argument must be locked by the caller using SyncMutexLock() (or the POSIX pthread_mutex_lock() cover routine). The kernel releases the mutex lock in the kernel when it blocks the thread on sync.

The blocked thread can be unblocked by any one of the following four conditions:

Condition variable signalled: The condition variable was signaled by a call to SyncCondvarSignal() which determined that this thread should be awakened.
Before returning from SyncCondvarWait(), mutex is reacquired. If mutex is locked, the thread enters into the STATE_MUTEX state waiting for mutex to be unlocked. At this point it's as though you had called SyncMutexLock(mutex).
Timeout: The wait was terminated by a timeout initiated by a previous call to TimerTimeout().
Before returning from SyncCondvarWait(), mutex is reacquired. If mutex is locked, the thread enters into the STATE_MUTEX state waiting for mutex to be unlocked. At this point it's as though you had called SyncMutexLock(mutex).
POSIX signal: The wait was terminated by an unmasked signal initiated by a call to SignalKill(). If a signal handler has been set up, the signal handler runs with mutex unlocked. On return from the signal handler, mutex is reacquired. If mutex is locked, the thread enters into the STATE_MUTEX state waiting for mutex to be unlocked. At this point, it's as though you had called SyncMutexLock(mutex).
Thread cancellation: The wait was terminated by a thread cancellation initiated by a call to ThreadCancel(). Before calling the cancellation handler, mutex is reacquired. If mutex is locked, the thread enters into the STATE_MUTEX state waiting for mutex to be unlocked. At this point, it's as though you had called SyncMutexLock(mutex).

In all cases, mutex is reacquired before the call returns. If the thread enters the STATE_MUTEX state, the rules governing SyncMutexLock() are in effect.

With condition variables, there is always a boolean predicate involving boolean shared variables associated with the condition wait that is true if the thread should proceed. Spurious wakeups may occur on timeout, signals and broadcast condition variable signals. Therefore, the predicate should always be reevaluated upon even a successful return. This is most easily accomplished with a while loop. For example:

SyncMutexLock(&mutex);

while(some_condition) {
    SyncCondvarWait(&condvar, &mutex);
}

SyncMutexUnlock(&mutex);

The sync argument must have been initialized by a call to SyncTypeCreate() or have been statically initialized by the manifest PTHREAD_COND_INITIALIZER.

Blocking states

STATE_CONDVAR: The calling thread blocks waiting for the condition variable to be signaled.
STATE_MUTEX: The thread was unblocked from the STATE_CONDVAR state and while trying to reacquire the controlling mutex, found the mutex was locked by another thread.

Returns:

The only difference between these functions is the way they indicate errors:

SyncCondvarWait(): If an error occurs, -1 is returned and errno is set. Any other value returned indicates success.
SyncCondvarWait_r(): EOK is returned on success. This function does NOT set errno. If an error occurs, any value in the Errors section may be returned.

Errors:

EAGAIN: On the first use of a statically initialized sync, all kernel synchronization objects were in use.
EFAULT: A fault occurred when the kernel tried to access sync or mutex.
EINVAL: The synchronization ID specified in sync doesn't exist.
ETIMEDOUT: A kernel timeout unblocked the call. See function TimerTimeout().

Classification:

QNX 6

Safety:
Cancellation point	Yes
Interrupt handler	No
Signal handler	Yes
Thread	Yes