NAME

catmutex_cond_wait - wait for condition variable to be signalled

SYNOPSIS

#include <cat/cat.h>

#include <cat/catmutex.h>

void catmutex_cond_wait(CATCOND *c, CATMUTEX *m);

DESCRIPTION

This function tests whether or not conditional variable c has been signalled. If not, the function atomically releases mutex m, which must have been locked, and suspends the calling thread until the condition variable is signalled by another thread calling catmutex_cond_signal.

On return, the variable may have been signalled and the mutex is held by this thread.

Condition variables are used with a mutex and an arbitrary condition. The mutex is used to protect the condition, both when changing it and when testing it.

NOTES

Even if catmutex_cond_wait() returns, the condition need not be true and must be explicitly tested.

The mutex must be held while modifying or testing the condition.

EXAMPLE

The standard way to use a condition variable is for one thread to wait for a condition to become true, as follows:

    catmutex_lock(&mutex);
    while ( condition is false ) {
        catmutex_cond_wait(&condvar, &mutex);
    }

    /* condition is true, mutex is held. */

    catmutex_unlock(&mutex);

Whenever the condition is changed, do something like:

    catmutex_lock(&mutex);

    /* Modify condition */

    catmutex_unlock(&mutex);
    catmutex_cond_signal(&cond);

If condition above would be ``testing whether or not an integer is greater than zero,'' the example would implement a counting semaphore.

SEE ALSO

cat, catutil

catmutex_cond_signal