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 releases the mutex. Must be called by the thread that owns the mutex.</P> 36<P>The calling thread is made runnable again by a call to <a href="OSSignalCond.html"><code>OSSignalCond()</code></a>. When this function returns, the calling thread will become the owner of the mutex.</P> 37<P>Note that the mutex is temporarily released regardless of how many times this thread may have locked the mutex with <code><a href="OSLockMutex.html">OSLockMutex()</a></code>. (When this thread re-acquires the mutex when the condition variable is signaled (via <a href="OSSignalCond.html"><code>OSSignalCond()</code></a>), the mutex lock count is restored, so each call to <code><a href="OSLockMutex.html">OSLockMutex()</a></code> must still have a matching call to <a href="OSUnlockMutex.html"><code>OSUnlockMutex()</code></a>. </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<P>This function may put the current thread to sleep. For precautions when calling similar functions, refer to <A href="../Interrupt/intro.html">Interrupts and Callback Functions</A>.</P> 43<H2>See Also</H2> 44<P><A href="../toc.html#Thread" target="contents">Thread Functions</A>, <A href="../toc.html#ThreadSynchronization" target="contents">Thread Synchronization Functions</A>,<BR> <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>, <A href="../Interrupt/intro.html">Interrupts and Callback Functions</A></P> 45<H2>Revision History</H2> 46<p> 472007/09/25 Added information on the sleeping status of threads.<br>2006/03/01 Initial version.<br> 48</p> 49<hr><p>CONFIDENTIAL</p></body> 50</HTML>