#include <revolution/os.h>void OSWaitCond(OSCond* cond, OSMutex* mutex); |
Pointer to condition variable. |
|
Pointer to mutex. |
None.
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 runnable again by a call to OSSignalCond(). 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 OSLockMutex(). (When this thread re-acquires the mutex when the condition variable is signaled (via OSSignalCond()), the mutex lock count is restored, so 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);
}This function may put the current thread to sleep. For precautions when calling similar functions, refer to Interrupts and Callback Functions.
Thread Functions, Thread Synchronization Functions,
OSInitCond, OSInitMutex, OSLockMutex, OSSignalCond, OSTryLockMutex, OSUnlockMutex, Interrupts and Callback Functions
2007/09/25 Added information on the sleeping status of threads.
2006/03/01 Initial version.
CONFIDENTIAL