OSWaitCond

Syntax

#include <revolution/os.h>

void OSWaitCond(OSCond* cond, OSMutex* mutex);

Arguments

*`cond`*	Pointer to condition variable.
*`mutex`*	Pointer to mutex.

Return Values

None.

Description

Blocks the calling thread on the condition variable and releases the mutex. Must be called by the thread that owns the mutex.

The calling thread is made executable again by a call to the OSSignalCond function. When this function returns, the calling thread will become the owner of the mutex.

Note that the mutex is temporarily released, regardless of how many times this thread may have locked the mutex with the OSLockMutex function.( When this thread re-acquires the mutex when the condition variable is signaled (through OSSignalCond), the mutex lock count is restored; thus, each call to OSLockMutex must still have a matching call to OSUnlockMutex.

An example of condition variable use is the following bounded buffer program.

u32 Append (u32 item, buffer * buf)
{
    OSLockMutex(&buf->mutex);
    while (buf->itemCount == MAX_BUF_SIZE)
    {
        OSWaitCond(buf->bufferNotFullCV, &buf->mutex);
    }
    // know that the buffer is not full and that I own the mutex
    InsertData(item, buf);
    OSUnlockMutex(&buf->mutex);
    // let any consumers know that the buffer is not empty anymore.
    OSSignalCond(&buf->bufferNotEmptyCV);
}

u32 Take (u32 * item, buffer * buf)
{
    OSLockMutex(&buf->mutex);
    while (buf->itemCount == 0)
    {
        OSWaitCond(buf->bufferNotEmptyCV, &buf->mutex);
    }
    // know that the buffer is not empty and that I own the mutex
    ExtractData(item, buf);
    OSUnlockMutex(&buf->mutex);
    // let any appenders know that the buffer is not full anymore.
    OSSignalCond(&buf->bufferNotFullCV);
}

Revision History

2006/03/01 Initial version.