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
13<H2>Syntax</H2>
14<dl><dd><pre class="construction">
15#include &lt;revolution/os.h&gt;
16
17void OSWaitCond(OSCond* cond, OSMutex* mutex);
18</pre></dd></dl>
19
20<H2>Arguments</H2>
21<TABLE class="arguments" border="1" >
22  <TBODY>
23    <TR>
24<TH><STRONG><EM><CODE>cond</CODE></EM></STRONG></TH>
25<TD>Pointer to condition variable.</TD>
26    </TR>
27    <TR>
28<TH><STRONG><EM><CODE>mutex</CODE></EM></STRONG></TH>
29<TD>Pointer to mutex.</TD>
30    </TR>
31  </TBODY>
32</TABLE>
33
34<H2>Return Values</H2>
35<P>None.</P>
36
37<H2>Description</H2>
38<P>Blocks the calling thread on the condition variable and releases the mutex. Must be called by the thread that owns the mutex.</P>
39<P>The calling thread is made executable again by a call to the <CODE>OSSignalCond</CODE> function. When this function returns, the calling thread will become the owner of the mutex.</P>
40<P>Note that the mutex is temporarily released, regardless of how many times this thread may have locked the mutex with the <CODE>OSLockMutex</CODE> function.( When this thread re-acquires the mutex when the condition variable is signaled (through <a href="OSSignalCond.html"><code>OSSignalCond</code></a>), the mutex lock count is restored; thus, 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>
41<P>An example of condition variable use is the following bounded buffer program.</P>
42<dl><dd><pre class="construction">
43u32 Append (u32 item, buffer * buf)
44{
45    OSLockMutex(&amp;buf-&gt;mutex);
46    while (buf-&gt;itemCount == MAX_BUF_SIZE)
47    {
48        OSWaitCond(buf-&gt;bufferNotFullCV, &amp;buf-&gt;mutex);
49    }
50    // know that the buffer is not full and that I own the mutex
51    InsertData(item, buf);
52    OSUnlockMutex(&amp;buf-&gt;mutex);
53    // let any consumers know that the buffer is not empty anymore.
54    OSSignalCond(&amp;buf-&gt;bufferNotEmptyCV);
55}
56</pre></dd></dl>
57<dl><dd><pre class="construction">
58u32 Take (u32 * item, buffer * buf)
59{
60    OSLockMutex(&amp;buf-&gt;mutex);
61    while (buf-&gt;itemCount == 0)
62    {
63        OSWaitCond(buf-&gt;bufferNotEmptyCV, &amp;buf-&gt;mutex);
64    }
65    // know that the buffer is not empty and that I own the mutex
66    ExtractData(item, buf);
67    OSUnlockMutex(&amp;buf-&gt;mutex);
68    // let any appenders know that the buffer is not full anymore.
69    OSSignalCond(&amp;buf-&gt;bufferNotFullCV);
70}
71</pre></dd></dl>
72
73<H2>See Also</H2>
74<P class="reference">
75<A href="../toc.html#Thread" target="contents">Thread Functions</A>,
76<A href="../toc.html#ThreadSynchronization" target="contents">Thread Synchronization Functions</A>,
77<A href="OSInitCond.html">OSInitCond</A>,
78<A href="OSInitMutex.html">OSInitMutex</A>,
79<A href="OSLockMutex.html">OSLockMutex</A>,
80<A href="OSSignalCond.html">OSSignalCond</A>,
81<A href="OSTryLockMutex.html">OSTryLockMutex</A>,
82<A href="OSUnlockMutex.html">OSUnlockMutex</A>
83</P>
84
85<H2>Revision History</H2>
86<P>
872006/03/01 Initial version.<br>
88</p>
89
90<hr><p>CONFIDENTIAL</p></body>
91</HTML>