OSWaitCond

Syntax

#include <cafe/os.h>

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

Parameters


cond Pointer to condition variable.
mutex Pointer to mutex.

Return Values

None.

Description

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

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

Note that the mutex is temporarily unlocked regardless of the number of times this thread may have locked the mutex with the OSLockMutex function. When this thread reacquires the mutex and notification is given of the condition variable (via the OSSignalCond function), the mutex lock count is restored; each call to the OSLockMutex function must have a corresponding call to the OSUnlockMutex function.

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);
    }

Do Not Call From

Callbacks Do not call this function from any callback function.

See Also

OSInitCond
OSInitMutex
OSLockMutex
OSSignalCond
OSTryLockMutex
OSUnlockMutex

Revision History

2013/05/08 Automated cleanup pass.
2012/08/01 Cleanup pass.
2010/08/30 Initial version.


CONFIDENTIAL