Mthreads

NAME

new_cond - allocate a new condition variable

delete_cond - free a condition variable

cond_init - initialize a condition variable

cond_empty - test whether there are waiting threads

cond_wait - block the calling thread

cond_signal - wake up one waiting thread

cond_broadcast - wake up all waiting threads

SYNOPSIS

#include <mthread.h>

cond_p new_cond(void);

void delete_cond(cond_p cvp);

cond_p cond_init(cond_p cvp);

int cond_empty(cond_p cvp);

void cond_wait(cond_p cvp, mutex_p mp);

void cond_signal(cond_p cvp);

void cond_broadcast(cond_p cvp);

DESCRIPTION

Condition variables are commonly used when one thread waits for another thread changing the value of some condition. If the other thread has changed the condition it signals this to one or all waiting threads which are then able to check the condition again. Usually testing this condition occures exclusively, protected by a mutex.

new_cond() allocates and initializes a new condition variable and returns a handle to the variable.

delete_cond() deletes a condition variable that has been allocated by new_cond().

cond_init() can be used to reinitialize a condition variable. This function is called by new_cond() implicitly.

cond_empty() tests whether or not there are waiting threads, that have been blocked on this condition variable.

cond_wait() blocks the calling thread on the condition variable cvp. If mp is not a null pointer but a valid pointer to a mutex, it will be freed after the thread has been blocked. When the thread is waked up this mutex will be reaquired before the thread returns from the call to cond_wait().

cond_signal() wakes up one of the waiting threads, if there are any. The thread will return with the mutex set again if a mutex handle has been passed to cond_wait(), so it can reevaluate the condition exclusively.

cond_broadcast() wakes up all of the waiting threads, if there are any. If a mutex handle has been passed to cond_wait(), all threads will return with the mutex set again. As only one thread may have the mutex set at a time, they will return serially. Each time the thread holding the mutex will release it, another thread may return from the cond_wait() call.

RETURN VALUES

Upon successful completion, both new_cond() and cond_init() return a handle to a condition variable. Otherwise a null handle is returned.

cond_empty() returns zero, if threads are blocked on the condition variable, otherwise it returns a non zero value.

ERRORS

new_cond() will fail if the following is true

[MENOMEM] there ist unsufficient memory to allocate a new condition variable

EXAMPLE

The example below shows the typical use of a condition variable cvp with the mutex mp to test a condition and wait until it is satisfied:

   mutex_lock(mp);
   while(/* condition is not satisfied */)
     cond_wait(cvp,mp);
   mutex_unlock(mp);