SyncCondvarWait(), SyncCondvarWait_r()

#include <sys/neutrino.h>

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

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

Arguments:

condvar

A pointer to a sync_t for the condition variable. You must have initialized this argument by calling SyncTypeCreate() or statically initialized it with the manifest PTHREAD_COND_INITIALIZER.

mutex

The mutex that's associated with the condition variable. You must lock this mutex by calling SyncMutexLock() (or the POSIX pthread_mutex_lock() cover routine). The kernel releases the mutex lock in the kernel when it blocks the thread on condvar.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The SyncCondvarWait() and SyncCondvarWait_r() kernel calls block the calling thread on the condition variable, condvar. If more than one thread is blocked on the object, the threads are queued in priority order.

These functions are similar, except in the way they indicate errors. See the Returns section for details.

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

Condition variable signalled

The condition variable was signaled by a call to SyncCondvarSignal(), that 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.

Condition variables are used to block a thread until a certain condition is satisfied. Currently, the only event that causes a spurious wakeup is when a thread waiting on a condition variable receives a signal and calls a signal handler, but the thread doesn't go back to waiting when the signal handler returns (instead pthread_cond_wait() returns zero). Note that the number of events that cause a spurious wakeup may increase with future releases. Therefore, you should always reevaluate the condition, even on a successful return. The easiest way to do this is with a while loop. For example:

SyncMutexLock(&mutex);

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

SyncMutexUnlock(&mutex);

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, the function returns -1 and sets errno. Any other value returned indicates success.

SyncCondvarWait_r()

Returns EOK on success. This function does NOT set errno. If an error occurs, the function returns any value in the Errors section.

Errors:

EFAULT

A fault occurred when the kernel tried to access condvar or mutex.

EINTR

A signal interrupted this function.

EINVAL

The synchronization ID specified in condvar doesn't exist.

ETIMEDOUT

A kernel timeout unblocked the call. See TimerTimeout().

Examples:

See pthread_cond_wait().

Classification:

QNX Neutrino