1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 2<HTML> 3<HEAD> 4<META http-equiv="Content-Type" content="text/html; charset=windows-1252"> 5<META name="GENERATOR" content="Microsoft FrontPage 5.0"> 6<META http-equiv="Content-Style-Type" content="text/css"> 7<LINK rel="stylesheet" type="text/css" href="../../CSS/revolution.css"> 8<TITLE>OSWaitCond</TITLE> 9</HEAD> 10<BODY> 11<H1>OSWaitCond</H1> 12<H2>C Specification</H2> 13<DL> 14 <DD> 15<PRE><CODE>#include <revolution/os.h></CODE></PRE> 16 <DD> 17<PRE><CODE>void OSWaitCond (OSCond* cond, OSMutex* mutex);</CODE></PRE> 18</DL> 19<H2>Arguments</H2> 20<TABLE border="1" cellpadding="3" cellspacing="0.1"> 21 <TBODY> 22 <TR> 23<TD width="120" bgcolor="#ffffe8"><I><B><CODE><STRONG><EM><CODE>cond</CODE></EM></STRONG></CODE></B></I></TD> 24<TD width="520">Pointer to condition variable.</TD> 25 </TR> 26 <TR> 27<TD width="120" bgcolor="#ffffe8"><I><B><CODE><STRONG><EM><CODE>mutex</CODE></EM></STRONG></CODE></B></I></TD> 28<TD width="520">Pointer to mutex.</TD> 29 </TR> 30 </TBODY> 31</TABLE> 32<H2>Return Values</H2> 33<P>None.</P> 34<H2>Description</H2> 35<P>Blocks the calling thread on the condition variable and unlocks the mutex. Must be called by the thread that owns the mutex.</P> 36<P>The calling thread is made runnable again by calling the <a href="OSSignalCond.html"><code>OSSignalCond</code></a> function. When this function returns, the calling thread will become the owner of the mutex.</P> 37<P>Note that the mutex is temporarily unlocked regardless of the number of times this thread may have locked the mutex with the <code><a href="OSLockMutex.html">OSLockMutex</a></code> function. When this thread reacquires the mutex and notification is given of the condition variable (via the <a href="OSSignalCond.html"><code>OSSignalCond</code></a> function), the mutex lock count is restored; therefore, each call to the <code><a href="OSLockMutex.html">OSLockMutex</a></code> function must have a corresponding call to the <a href="OSUnlockMutex.html"><code>OSUnlockMutex</code></a> function. </P> 38<P>An example of condition variable use is the following bounded buffer program.</P> 39<BLOCKQUOTE><code>u32 Append (u32 item, buffer * buf)<br> {<br> OSLockMutex(&buf->mutex);<br> while (buf->itemCount == MAX_BUF_SIZE)<br> {<br> OSWaitCond(buf->bufferNotFullCV, &buf->mutex);<br> }<br> // know that the buffer is not full and that I own the mutex<br> InsertData(item, buf);<br> OSUnlockMutex(&buf->mutex);<br> // let any consumers know that the buffer is not empty anymore.<br> OSSignalCond(&buf->bufferNotEmptyCV);<BR> }</CODE></BLOCKQUOTE> 40<BLOCKQUOTE><code>u32 Take (u32 * item, buffer * buf)<br> {<br> OSLockMutex(&buf->mutex);<br> while (buf->itemCount == 0)<br> {<br> OSWaitCond(buf->bufferNotEmptyCV, &buf->mutex);<br> }<br> // know that the buffer is not empty and that I own the mutex<br> ExtractData(item, buf);<br> OSUnlockMutex(&buf->mutex);<br> // let any appenders know that the buffer is not full anymore.<br> OSSignalCond(&buf->bufferNotFullCV);<BR> }</CODE></BLOCKQUOTE> 41 42<H2>See Also</H2> 43<P><a href="../list.html#Thread" target="contents">Thread Functions</a>, <a href="../list.html#ThreadSynchronization" target="contents">Thread Synchronization Functions</a>, <a href="OSInitCond.html"><code>OSInitCond</code></a>, <a href="OSInitMutex.html"><code>OSInitMutex</code></a>, <a href="OSLockMutex.html"><code>OSLockMutex</code></a>, <a href="OSSignalCond.html"><code>OSSignalCond</code></a>, <a href="OSTryLockMutex.html"><code>OSTryLockMutex</code></a>, <a href="OSUnlockMutex.html"><code>OSUnlockMutex</code></a></P> 44<H2>Revision History</H2> 45<P></P> 46<P>03/01/2006 Initial version.</p> 47</BODY> 48</HTML>