<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en_US" lang="en_US">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- waitconditions.qdoc -->
<title>Qt 4.8: Wait Conditions Example</title>
<link rel="stylesheet" type="text/css" href="style/style.css" />
<script src="scripts/jquery.js" type="text/javascript"></script>
<script src="scripts/functions.js" type="text/javascript"></script>
<link rel="stylesheet" type="text/css" href="style/superfish.css" />
<link rel="stylesheet" type="text/css" href="style/narrow.css" />
<!--[if IE]>
<meta name="MSSmartTagsPreventParsing" content="true">
<meta http-equiv="imagetoolbar" content="no">
<![endif]-->
<!--[if lt IE 7]>
<link rel="stylesheet" type="text/css" href="style/style_ie6.css">
<![endif]-->
<!--[if IE 7]>
<link rel="stylesheet" type="text/css" href="style/style_ie7.css">
<![endif]-->
<!--[if IE 8]>
<link rel="stylesheet" type="text/css" href="style/style_ie8.css">
<![endif]-->
<script src="scripts/superfish.js" type="text/javascript"></script>
<script src="scripts/narrow.js" type="text/javascript"></script>
</head>
<body class="" onload="CheckEmptyAndLoadList();">
<div class="header" id="qtdocheader">
<div class="content">
<div id="nav-logo">
<a href="index.html">Home</a></div>
<a href="index.html" class="qtref"><span>Qt Reference Documentation</span></a>
<div id="narrowsearch"></div>
<div id="nav-topright">
<ul>
<li class="nav-topright-home"><a href="http://qt.digia.com/">Qt HOME</a></li>
<li class="nav-topright-dev"><a href="http://qt-project.org/">DEV</a></li>
<li class="nav-topright-doc nav-topright-doc-active"><a href="http://qt-project.org/doc/">
DOC</a></li>
<li class="nav-topright-blog"><a href="http://blog.qt.digia.com/">BLOG</a></li>
</ul>
</div>
<div id="shortCut">
<ul>
<li class="shortCut-topleft-inactive"><span><a href="index.html">Qt 4.8</a></span></li>
<li class="shortCut-topleft-active"><a href="http://qt-project.org/doc/">ALL VERSIONS </a></li>
</ul>
</div>
<ul class="sf-menu" id="narrowmenu">
<li><a href="#">API Lookup</a>
<ul>
<li><a href="classes.html">Class index</a></li>
<li><a href="functions.html">Function index</a></li>
<li><a href="modules.html">Modules</a></li>
<li><a href="namespaces.html">Namespaces</a></li>
<li><a href="qtglobal.html">Global Declarations</a></li>
<li><a href="qdeclarativeelements.html">QML elements</a></li>
</ul>
</li>
<li><a href="#">Qt Topics</a>
<ul>
<li><a href="qt-basic-concepts.html">Programming with Qt</a></li>
<li><a href="qtquick.html">Device UIs & Qt Quick</a></li>
<li><a href="qt-gui-concepts.html">UI Design with Qt</a></li>
<li><a href="supported-platforms.html">Supported Platforms</a></li>
<li><a href="technology-apis.html">Qt and Key Technologies</a></li>
<li><a href="best-practices.html">How-To's and Best Practices</a></li>
</ul>
</li>
<li><a href="#">Examples</a>
<ul>
<li><a href="all-examples.html">Examples</a></li>
<li><a href="tutorials.html">Tutorials</a></li>
<li><a href="demos.html">Demos</a></li>
<li><a href="qdeclarativeexamples.html">QML Examples</a></li>
</ul>
</li>
</ul>
</div>
</div>
<div class="wrapper">
<div class="hd">
<span></span>
</div>
<div class="bd group">
<div class="sidebar">
<div class="searchlabel">
Search index:</div>
<div class="search" id="sidebarsearch">
<form id="qtdocsearch" action="" onsubmit="return false;">
<fieldset>
<input type="text" name="searchstring" id="pageType" value="" />
<div id="resultdialog">
<a href="#" id="resultclose">Close</a>
<p id="resultlinks" class="all"><a href="#" id="showallresults">All</a> | <a href="#" id="showapiresults">API</a> | <a href="#" id="showarticleresults">Articles</a> | <a href="#" id="showexampleresults">Examples</a></p>
<p id="searchcount" class="all"><span id="resultcount"></span><span id="apicount"></span><span id="articlecount"></span><span id="examplecount"></span> results:</p>
<ul id="resultlist" class="all">
</ul>
</div>
</fieldset>
</form>
</div>
<div class="box first bottombar" id="lookup">
<h2 title="API Lookup"><span></span>
API Lookup</h2>
<div id="list001" class="list">
<ul id="ul001" >
<li class="defaultLink"><a href="classes.html">Class index</a></li>
<li class="defaultLink"><a href="functions.html">Function index</a></li>
<li class="defaultLink"><a href="modules.html">Modules</a></li>
<li class="defaultLink"><a href="namespaces.html">Namespaces</a></li>
<li class="defaultLink"><a href="qtglobal.html">Global Declarations</a></li>
<li class="defaultLink"><a href="qdeclarativeelements.html">QML elements</a></li>
</ul>
</div>
</div>
<div class="box bottombar" id="topics">
<h2 title="Qt Topics"><span></span>
Qt Topics</h2>
<div id="list002" class="list">
<ul id="ul002" >
<li class="defaultLink"><a href="qt-basic-concepts.html">Programming with Qt</a></li>
<li class="defaultLink"><a href="qtquick.html">Device UIs & Qt Quick</a></li>
<li class="defaultLink"><a href="qt-gui-concepts.html">UI Design with Qt</a></li>
<li class="defaultLink"><a href="supported-platforms.html">Supported Platforms</a></li>
<li class="defaultLink"><a href="technology-apis.html">Qt and Key Technologies</a></li>
<li class="defaultLink"><a href="best-practices.html">How-To's and Best Practices</a></li>
</ul>
</div>
</div>
<div class="box" id="examples">
<h2 title="Examples"><span></span>
Examples</h2>
<div id="list003" class="list">
<ul id="ul003">
<li class="defaultLink"><a href="all-examples.html">Examples</a></li>
<li class="defaultLink"><a href="tutorials.html">Tutorials</a></li>
<li class="defaultLink"><a href="demos.html">Demos</a></li>
<li class="defaultLink"><a href="qdeclarativeexamples.html">QML Examples</a></li>
</ul>
</div>
</div>
</div>
<div class="wrap">
<div class="toolbar">
<div class="breadcrumb toolblock">
<ul>
<li class="first"><a href="index.html">Home</a></li>
<!-- Breadcrumbs go here -->
<li><a href="all-examples.html">Examples</a></li>
<li>Wait Conditions Example</li>
</ul>
</div>
<div class="toolbuttons toolblock">
<ul>
<li id="smallA" class="t_button">A</li>
<li id="medA" class="t_button active">A</li>
<li id="bigA" class="t_button">A</li>
<li id="print" class="t_button"><a href="javascript:this.print();">
<span>Print</span></a></li>
</ul>
</div>
</div>
<div class="content mainContent">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#global-variables">Global Variables</a></li>
<li class="level1"><a href="#producer-class">Producer Class</a></li>
<li class="level1"><a href="#consumer-class">Consumer Class</a></li>
<li class="level1"><a href="#the-main-function">The main() Function</a></li>
</ul>
</div>
<h1 class="title">Wait Conditions Example</h1>
<span class="subtitle"></span>
<!-- $$$threads/waitconditions-description -->
<div class="descr"> <a name="details"></a>
<p>Files:</p>
<ul>
<li><a href="threads-waitconditions-waitconditions-cpp.html">threads/waitconditions/waitconditions.cpp</a></li>
<li><a href="threads-waitconditions-waitconditions-pro.html">threads/waitconditions/waitconditions.pro</a></li>
</ul>
<p>The Wait Conditions example shows how to use <a href="qwaitcondition.html">QWaitCondition</a> and <a href="qmutex.html">QMutex</a> to control access to a circular buffer shared by a producer thread and a consumer thread.<p>The producer writes data to the buffer until it reaches the end of the buffer, at which point it restarts from the beginning, overwriting existing data. The consumer thread reads the data as it is produced and writes it to standard error.</p>
<p>Wait conditions make it possible to have a higher level of concurrency than what is possible with mutexes alone. If accesses to the buffer were simply guarded by a <a href="qmutex.html">QMutex</a>, the consumer thread couldn't access the buffer at the same time as the producer thread. Yet, there is no harm in having both threads working on <i>different parts</i> of the buffer at the same time.</p>
<p>The example comprises two classes: <tt>Producer</tt> and <tt>Consumer</tt>. Both inherit from <a href="qthread.html">QThread</a>. The circular buffer used for communicating between these two classes and the synchronization tools that protect it are global variables.</p>
<p>An alternative to using <a href="qwaitcondition.html">QWaitCondition</a> and <a href="qmutex.html">QMutex</a> to solve the producer-consumer problem is to use <a href="qsemaphore.html">QSemaphore</a>. This is what the <a href="threads-semaphores.html">Semaphores</a> example does.</p>
<a name="global-variables"></a>
<h2>Global Variables</h2>
<p>Let's start by reviewing the circular buffer and the associated synchronization tools:</p>
<pre class="cpp"> <span class="preprocessor">#ifdef Q_WS_S60</span>
<span class="keyword">const</span> <span class="type">int</span> DataSize <span class="operator">=</span> <span class="number">300</span>;
<span class="preprocessor">#else</span>
<span class="keyword">const</span> <span class="type">int</span> DataSize <span class="operator">=</span> <span class="number">100000</span>;
<span class="preprocessor">#endif</span>
<span class="keyword">const</span> <span class="type">int</span> BufferSize <span class="operator">=</span> <span class="number">8192</span>;
<span class="type">char</span> buffer<span class="operator">[</span>BufferSize<span class="operator">]</span>;
<span class="type"><a href="qwaitcondition.html">QWaitCondition</a></span> bufferNotEmpty;
<span class="type"><a href="qwaitcondition.html">QWaitCondition</a></span> bufferNotFull;
<span class="type"><a href="qmutex.html">QMutex</a></span> mutex;
<span class="type">int</span> numUsedBytes <span class="operator">=</span> <span class="number">0</span>;</pre>
<p><tt>DataSize</tt> is the amount of data that the producer will generate. To keep the example as simple as possible, we make it a constant. <tt>BufferSize</tt> is the size of the circular buffer. It is less than <tt>DataSize</tt>, meaning that at some point the producer will reach the end of the buffer and restart from the beginning.</p>
<p>To synchronize the producer and the consumer, we need two wait conditions and one mutex. The <tt>bufferNotEmpty</tt> condition is signalled when the producer has generated some data, telling the consumer that it can start reading it. The <tt>bufferNotFull</tt> condition is signalled when the consumer has read some data, telling the producer that it can generate more. The <tt>numUsedBytes</tt> is the number of bytes in the buffer that contain data.</p>
<p>Together, the wait conditions, the mutex, and the <tt>numUsedBytes</tt> counter ensure that the producer is never more than <tt>BufferSize</tt> bytes ahead of the consumer, and that the consumer never reads data that the producer hasn't generated yet.</p>
<a name="producer-class"></a>
<h2>Producer Class</h2>
<p>Let's review the code for the <tt>Producer</tt> class:</p>
<pre class="cpp"> <span class="keyword">class</span> Producer : <span class="keyword">public</span> <span class="type"><a href="qthread.html">QThread</a></span>
{
<span class="keyword">public</span>:
Producer(<span class="type"><a href="qobject.html">QObject</a></span> <span class="operator">*</span>parent <span class="operator">=</span> NULL) : <span class="type"><a href="qthread.html">QThread</a></span>(parent)
{
}
<span class="type">void</span> run()
{
qsrand(<span class="type"><a href="qtime.html">QTime</a></span>(<span class="number">0</span><span class="operator">,</span><span class="number">0</span><span class="operator">,</span><span class="number">0</span>)<span class="operator">.</span>secsTo(<span class="type"><a href="qtime.html">QTime</a></span><span class="operator">::</span>currentTime()));
<span class="keyword">for</span> (<span class="type">int</span> i <span class="operator">=</span> <span class="number">0</span>; i <span class="operator"><</span> DataSize; <span class="operator">+</span><span class="operator">+</span>i) {
mutex<span class="operator">.</span>lock();
<span class="keyword">if</span> (numUsedBytes <span class="operator">=</span><span class="operator">=</span> BufferSize)
bufferNotFull<span class="operator">.</span>wait(<span class="operator">&</span>mutex);
mutex<span class="operator">.</span>unlock();
buffer<span class="operator">[</span>i <span class="operator">%</span> BufferSize<span class="operator">]</span> <span class="operator">=</span> <span class="string">"ACGT"</span><span class="operator">[</span>(<span class="type">int</span>)qrand() <span class="operator">%</span> <span class="number">4</span><span class="operator">]</span>;
mutex<span class="operator">.</span>lock();
<span class="operator">+</span><span class="operator">+</span>numUsedBytes;
bufferNotEmpty<span class="operator">.</span>wakeAll();
mutex<span class="operator">.</span>unlock();
}
}
};</pre>
<p>The producer generates <tt>DataSize</tt> bytes of data. Before it writes a byte to the circular buffer, it must first check whether the buffer is full (i.e., <tt>numUsedBytes</tt> equals <tt>BufferSize</tt>). If the buffer is full, the thread waits on the <tt>bufferNotFull</tt> condition.</p>
<p>At the end, the producer increments <tt>numUsedBytes</tt> and signalls that the condition <tt>bufferNotEmpty</tt> is true, since <tt>numUsedBytes</tt> is necessarily greater than 0.</p>
<p>We guard all accesses to the <tt>numUsedBytes</tt> variable with a mutex. In addition, the <a href="qwaitcondition.html#wait">QWaitCondition::wait</a>() function accepts a mutex as its argument. This mutex is unlocked before the thread is put to sleep and locked when the thread wakes up. Furthermore, the transition from the locked state to the wait state is atomic, to prevent race conditions from occurring.</p>
<a name="consumer-class"></a>
<h2>Consumer Class</h2>
<p>Let's turn to the <tt>Consumer</tt> class:</p>
<pre class="cpp"> <span class="keyword">class</span> Consumer : <span class="keyword">public</span> <span class="type"><a href="qthread.html">QThread</a></span>
{
Q_OBJECT
<span class="keyword">public</span>:
Consumer(<span class="type"><a href="qobject.html">QObject</a></span> <span class="operator">*</span>parent <span class="operator">=</span> NULL) : <span class="type"><a href="qthread.html">QThread</a></span>(parent)
{
}
<span class="type">void</span> run()
{
<span class="keyword">for</span> (<span class="type">int</span> i <span class="operator">=</span> <span class="number">0</span>; i <span class="operator"><</span> DataSize; <span class="operator">+</span><span class="operator">+</span>i) {
mutex<span class="operator">.</span>lock();
<span class="keyword">if</span> (numUsedBytes <span class="operator">=</span><span class="operator">=</span> <span class="number">0</span>)
bufferNotEmpty<span class="operator">.</span>wait(<span class="operator">&</span>mutex);
mutex<span class="operator">.</span>unlock();
<span class="preprocessor">#ifdef Q_WS_S60</span>
<span class="keyword">emit</span> stringConsumed(<span class="type"><a href="qstring.html">QString</a></span>(buffer<span class="operator">[</span>i <span class="operator">%</span> BufferSize<span class="operator">]</span>));
<span class="preprocessor">#else</span>
fprintf(stderr<span class="operator">,</span> <span class="string">"%c"</span><span class="operator">,</span> buffer<span class="operator">[</span>i <span class="operator">%</span> BufferSize<span class="operator">]</span>);
<span class="preprocessor">#endif</span>
mutex<span class="operator">.</span>lock();
<span class="operator">-</span><span class="operator">-</span>numUsedBytes;
bufferNotFull<span class="operator">.</span>wakeAll();
mutex<span class="operator">.</span>unlock();
}
fprintf(stderr<span class="operator">,</span> <span class="string">"\n"</span>);
}
<span class="keyword">signals</span>:
<span class="type">void</span> stringConsumed(<span class="keyword">const</span> <span class="type"><a href="qstring.html">QString</a></span> <span class="operator">&</span>text);
};</pre>
<p>The code is very similar to the producer. Before we read the byte, we check whether the buffer is empty (<tt>numUsedBytes</tt> is 0) instead of whether it's full and wait on the <tt>bufferNotEmpty</tt> condition if it's empty. After we've read the byte, we decrement <tt>numUsedBytes</tt> (instead of incrementing it), and we signal the <tt>bufferNotFull</tt> condition (instead of the <tt>bufferNotEmpty</tt> condition).</p>
<a name="the-main-function"></a>
<h2>The main() Function</h2>
<p>In <tt>main()</tt>, we create the two threads and call <a href="qthread.html#wait">QThread::wait</a>() to ensure that both threads get time to finish before we exit:</p>
<pre class="cpp"> <span class="type">int</span> main(<span class="type">int</span> argc<span class="operator">,</span> <span class="type">char</span> <span class="operator">*</span>argv<span class="operator">[</span><span class="operator">]</span>)
{
<span class="preprocessor">#ifdef Q_WS_S60</span>
<span class="type"><a href="qapplication.html">QApplication</a></span> app(argc<span class="operator">,</span> argv);
PlainTextEdit console;
console<span class="operator">.</span>showMaximized();
<span class="keyword">return</span> app<span class="operator">.</span>exec();
<span class="preprocessor">#else</span>
<span class="type"><a href="qcoreapplication.html">QCoreApplication</a></span> app(argc<span class="operator">,</span> argv);
Producer producer;
Consumer consumer;
producer<span class="operator">.</span>start();
consumer<span class="operator">.</span>start();
producer<span class="operator">.</span>wait();
consumer<span class="operator">.</span>wait();
<span class="keyword">return</span> <span class="number">0</span>;
<span class="preprocessor">#endif</span>
}</pre>
<p>So what happens when we run the program? Initially, the producer thread is the only one that can do anything; the consumer is blocked waiting for the <tt>bufferNotEmpty</tt> condition to be signalled (<tt>numUsedBytes</tt> is 0). Once the producer has put one byte in the buffer, <tt>numUsedBytes</tt> is <tt>BufferSize</tt> - 1 and the <tt>bufferNotEmpty</tt> condition is signalled. At that point, two things can happen: Either the consumer thread takes over and reads that byte, or the consumer gets to produce a second byte.</p>
<p>The producer-consumer model presented in this example makes it possible to write highly concurrent multithreaded applications. On a multiprocessor machine, the program is potentially up to twice as fast as the equivalent mutex-based program, since the two threads can be active at the same time on different parts of the buffer.</p>
<p>Be aware though that these benefits aren't always realized. Locking and unlocking a <a href="qmutex.html">QMutex</a> has a cost. In practice, it would probably be worthwhile to divide the buffer into chunks and to operate on chunks instead of individual bytes. The buffer size is also a parameter that must be selected carefully, based on experimentation.</p>
</div>
<!-- @@@threads/waitconditions -->
</div>
</div>
</div>
<div class="ft">
<span></span>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2015 The Qt Company Ltd.
Documentation contributions included herein are the copyrights of
their respective owners.</p>
<br />
<p>
The documentation provided herein is licensed under the terms of the
<a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation
License version 1.3</a> as published by the Free Software Foundation.</p>
<p>
Documentation sources may be obtained from <a href="http://www.qt-project.org">
www.qt-project.org</a>.</p>
<br />
<p>
Qt and respective logos are trademarks of The Qt Company Ltd
in Finland and/or other countries worldwide. All other trademarks are property
of their respective owners. <a title="Privacy Policy"
href="http://en.gitorious.org/privacy_policy/">Privacy Policy</a></p>
</div>
<script src="scripts/functions.js" type="text/javascript"></script>
</body>
</html>
