<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "DTD/xhtml1-strict.dtd">
<html><head><title>QThreadPool Class Reference</title><style>h3.fn,span.fn { margin-left: 1cm; text-indent: -1cm }
a:link { color: #004faf; text-decoration: none }
a:visited { color: #672967; text-decoration: none }
td.postheader { font-family: sans-serif }
tr.address { font-family: sans-serif }
body { background: #ffffff; color: black; }
</style></head><body><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr /><td align="left" valign="top" width="32"><img align="left" border="0" height="32" src="images/rb-logo.png" width="32" /></td><td width="1">  </td><td class="postheader" valign="center"><a href="index.html"><font color="#004faf">Home</font></a> · <a href="classes.html"><font color="#004faf">All Classes</font></a> · <a href="modules.html"><font color="#004faf">Modules</font></a></td></table><h1 align="center">QThreadPool Class Reference<br /><sup><sup>[<a href="qtcore.html">QtCore</a> module]</sup></sup></h1><p>The QThreadPool class manages a collection of QThreads. <a href="#details">More...</a></p>
<p>Inherits <a href="qobject.html">QObject</a>.</p><h3>Methods</h3><ul><li><div class="fn" /><b><a href="qthreadpool.html#QThreadPool">__init__</a></b> (<i>self</i>, QObject <i>parent</i> = None)</li><li><div class="fn" />int <b><a href="qthreadpool.html#activeThreadCount">activeThreadCount</a></b> (<i>self</i>)</li><li><div class="fn" />int <b><a href="qthreadpool.html#expiryTimeout">expiryTimeout</a></b> (<i>self</i>)</li><li><div class="fn" />int <b><a href="qthreadpool.html#maxThreadCount">maxThreadCount</a></b> (<i>self</i>)</li><li><div class="fn" /><b><a href="qthreadpool.html#releaseThread">releaseThread</a></b> (<i>self</i>)</li><li><div class="fn" /><b><a href="qthreadpool.html#reserveThread">reserveThread</a></b> (<i>self</i>)</li><li><div class="fn" /><b><a href="qthreadpool.html#setExpiryTimeout">setExpiryTimeout</a></b> (<i>self</i>, int <i>expiryTimeout</i>)</li><li><div class="fn" /><b><a href="qthreadpool.html#setMaxThreadCount">setMaxThreadCount</a></b> (<i>self</i>, int <i>maxThreadCount</i>)</li><li><div class="fn" /><b><a href="qthreadpool.html#start">start</a></b> (<i>self</i>, QRunnable <i>runnable</i>, int <i>priority</i> = 0)</li><li><div class="fn" />bool <b><a href="qthreadpool.html#tryStart">tryStart</a></b> (<i>self</i>, QRunnable <i>runnable</i>)</li><li><div class="fn" /><b><a href="qthreadpool.html#waitForDone">waitForDone</a></b> (<i>self</i>)</li><li><div class="fn" />bool <b><a href="qthreadpool.html#waitForDone-2">waitForDone</a></b> (<i>self</i>, int <i>msecs</i>)</li></ul><h3>Static Methods</h3><ul><li><div class="fn" />QThreadPool <b><a href="qthreadpool.html#globalInstance">globalInstance</a></b> ()</li></ul><a name="details" /><hr /><h2>Detailed Description</h2><p>The QThreadPool class manages a collection of QThreads.</p>
<p>QThreadPool manages and recyles individual <a href="qthread.html">QThread</a> objects to help reduce thread creation
costs in programs that use threads. Each Qt application has one
global QThreadPool object, which can be accessed by calling
<a href="qthreadpool.html#globalInstance">globalInstance</a>().</p>
<p>To use one of the QThreadPool threads, subclass <a href="qrunnable.html">QRunnable</a> and implement the run() virtual
function. Then create an object of that class and pass it to
<a href="qthreadpool.html#start">QThreadPool.start</a>().</p>
<pre class="cpp">
<span class="keyword">class</span> HelloWorldTask : <span class="keyword">public</span> <span class="type"><a href="qrunnable.html">QRunnable</a></span>
{
<span class="type">void</span> run()
{
<a href="qtcore.html#qDebug">qDebug</a>() <span class="operator"><</span><span class="operator"><</span> <span class="string">"Hello world from thread"</span> <span class="operator"><</span><span class="operator"><</span> <span class="type"><a href="qthread.html">QThread</a></span><span class="operator">.</span>currentThread();
}
}
HelloWorldTask <span class="operator">*</span>hello <span class="operator">=</span> <span class="keyword">new</span> HelloWorldTask();
<span class="comment">// QThreadPool takes ownership and deletes 'hello' automatically</span>
<span class="type">QThreadPool</span><span class="operator">.</span><a href="qthreadpool.html#globalInstance">globalInstance</a>()<span class="operator">-</span><span class="operator">></span><a href="qthreadpool.html#start">start</a>(hello);
</pre>
<p>QThreadPool deletes the <a href="qrunnable.html">QRunnable</a>
automatically by default. Use <a href="qrunnable.html#setAutoDelete">QRunnable.setAutoDelete</a>() to
change the auto-deletion flag.</p>
<p>QThreadPool supports executing the same <a href="qrunnable.html">QRunnable</a> more than once by calling
tryStart(this) from within <a href="qrunnable.html#run">QRunnable.run</a>(). If autoDelete is enabled
the <a href="qrunnable.html">QRunnable</a> will be deleted when the
last thread exits the run function. Calling <a href="qthreadpool.html#start">start</a>() multiple times with the same
<a href="qrunnable.html">QRunnable</a> when autoDelete is enabled
creates a race condition and is not recommended.</p>
<p>Threads that are unused for a certain amount of time will
expire. The default expiry timeout is 30000 milliseconds (30
seconds). This can be changed using <a href="qthreadpool.html#expiryTimeout-prop">setExpiryTimeout</a>().
Setting a negative expiry timeout disables the expiry
mechanism.</p>
<p>Call <a href="qthreadpool.html#maxThreadCount-prop">maxThreadCount</a>() to
query the maximum number of threads to be used. If needed, you can
change the limit with <a href="qthreadpool.html#maxThreadCount-prop">setMaxThreadCount</a>(). The
default <a href="qthreadpool.html#maxThreadCount-prop">maxThreadCount</a>() is
<a href="qthread.html#idealThreadCount">QThread.idealThreadCount</a>().
The <a href="qthreadpool.html#activeThreadCount-prop">activeThreadCount</a>()
function returns the number of threads currently doing work.</p>
<p>The <a href="qthreadpool.html#reserveThread">reserveThread</a>()
function reserves a thread for external use. Use <a href="qthreadpool.html#releaseThread">releaseThread</a>() when your are
done with the thread, so that it may be reused. Essentially, these
functions temporarily increase or reduce the active thread count
and are useful when implementing time-consuming operations that are
not visible to the QThreadPool.</p>
<p>Note that QThreadPool is a low-level class for managing threads,
see <a href="qtconcurrentrun.html#run">QtConcurrent.run</a>() or
the other <a href="threads-qtconcurrent.html">Qt Concurrent</a>
APIs for higher level alternatives.</p>
<hr /><h2>Method Documentation</h2><h3 class="fn"><a name="QThreadPool" />QThreadPool.__init__ (<i>self</i>, <a href="qobject.html">QObject</a> <i>parent</i> = None)</h3><p>The <i>parent</i> argument, if not None, causes <i>self</i> to be owned by Qt instead of PyQt.</p><p>Constructs a thread pool with the given <i>parent</i>.</p>
<h3 class="fn"><a name="activeThreadCount" />int QThreadPool.activeThreadCount (<i>self</i>)</h3><h3 class="fn"><a name="expiryTimeout" />int QThreadPool.expiryTimeout (<i>self</i>)</h3><h3 class="fn"><a name="globalInstance" /><a href="qthreadpool.html">QThreadPool</a> QThreadPool.globalInstance ()</h3><p>Returns the global <a href="qthreadpool.html">QThreadPool</a>
instance.</p>
<h3 class="fn"><a name="maxThreadCount" />int QThreadPool.maxThreadCount (<i>self</i>)</h3><h3 class="fn"><a name="releaseThread" />QThreadPool.releaseThread (<i>self</i>)</h3><p>Releases a thread previously reserved by a call to <a href="qthreadpool.html#reserveThread">reserveThread</a>().</p>
<p><b>Note:</b> Calling this function without previously reserving
a thread temporarily increases <a href="qthreadpool.html#maxThreadCount-prop">maxThreadCount</a>(). This
is useful when a thread goes to sleep waiting for more work,
allowing other threads to continue. Be sure to call <a href="qthreadpool.html#reserveThread">reserveThread</a>() when done
waiting, so that the thread pool can correctly maintain the
<a href="qthreadpool.html#activeThreadCount-prop">activeThreadCount</a>().</p>
<p><b>See also</b> <a href="qthreadpool.html#reserveThread">reserveThread</a>().</p>
<h3 class="fn"><a name="reserveThread" />QThreadPool.reserveThread (<i>self</i>)</h3><p>Reserves one thread, disregarding <a href="qthreadpool.html#activeThreadCount-prop">activeThreadCount</a>()
and <a href="qthreadpool.html#maxThreadCount-prop">maxThreadCount</a>().</p>
<p>Once you are done with the thread, call <a href="qthreadpool.html#releaseThread">releaseThread</a>() to allow it to
be reused.</p>
<p><b>Note:</b> This function will always increase the number of
active threads. This means that by using this function, it is
possible for <a href="qthreadpool.html#activeThreadCount-prop">activeThreadCount</a>()
to return a value greater than <a href="qthreadpool.html#maxThreadCount-prop">maxThreadCount</a>() .</p>
<p><b>See also</b> <a href="qthreadpool.html#releaseThread">releaseThread</a>().</p>
<h3 class="fn"><a name="setExpiryTimeout" />QThreadPool.setExpiryTimeout (<i>self</i>, int <i>expiryTimeout</i>)</h3><h3 class="fn"><a name="setMaxThreadCount" />QThreadPool.setMaxThreadCount (<i>self</i>, int <i>maxThreadCount</i>)</h3><h3 class="fn"><a name="start" />QThreadPool.start (<i>self</i>, <a href="qrunnable.html">QRunnable</a> <i>runnable</i>, int <i>priority</i> = 0)</h3><p>Reserves a thread and uses it to run <i>runnable</i>, unless
this thread will make the current thread count exceed <a href="qthreadpool.html#maxThreadCount-prop">maxThreadCount</a>(). In
that case, <i>runnable</i> is added to a run queue instead. The
<i>priority</i> argument can be used to control the run queue's
order of execution.</p>
<p>Note that the thread pool takes ownership of the <i>runnable</i>
if <a href="qrunnable.html#autoDelete">runnable->autoDelete()</a> returns
true, and the <i>runnable</i> will be deleted automatically by the
thread pool after the <a href="qrunnable.html#run">runnable->run()</a> returns. If <a href="qrunnable.html#autoDelete">runnable->autoDelete()</a> returns
false, ownership of <i>runnable</i> remains with the caller. Note
that changing the auto-deletion on <i>runnable</i> after calling
this functions results in undefined behavior.</p>
<h3 class="fn"><a name="tryStart" />bool QThreadPool.tryStart (<i>self</i>, <a href="qrunnable.html">QRunnable</a> <i>runnable</i>)</h3><p>Attempts to reserve a thread to run <i>runnable</i>.</p>
<p>If no threads are available at the time of calling, then this
function does nothing and returns false. Otherwise, <i>runnable</i>
is run immediately using one available thread and this function
returns true.</p>
<p>Note that the thread pool takes ownership of the <i>runnable</i>
if <a href="qrunnable.html#autoDelete">runnable->autoDelete()</a> returns
true, and the <i>runnable</i> will be deleted automatically by the
thread pool after the <a href="qrunnable.html#run">runnable->run()</a> returns. If <a href="qrunnable.html#autoDelete">runnable->autoDelete()</a> returns
false, ownership of <i>runnable</i> remains with the caller. Note
that changing the auto-deletion on <i>runnable</i> after calling
this function results in undefined behavior.</p>
<h3 class="fn"><a name="waitForDone" />QThreadPool.waitForDone (<i>self</i>)</h3><p>Waits for each thread to exit and removes all threads from the
thread pool.</p>
<h3 class="fn"><a name="waitForDone-2" />bool QThreadPool.waitForDone (<i>self</i>, int <i>msecs</i>)</h3><p>This function overloads <a href="qthreadpool.html#waitForDone">waitForDone</a>().</p>
<p>Waits up to <i>msecs</i> milliseconds for all threads to exit
and removes all threads from the thread pool. Returns true if all
threads were removed; otherwise it returns false.</p>
<p>This function was introduced in Qt 4.8.</p>
<address><hr /><div align="center"><table border="0" cellspacing="0" width="100%"><tr class="address"><td align="left" width="25%">PyQt 4.10.3 for X11</td><td align="center" width="50%">Copyright © <a href="http://www.riverbankcomputing.com">Riverbank Computing Ltd</a> and <a href="http://www.qtsoftware.com">Nokia</a> 2012</td><td align="right" width="25%">Qt 4.8.5</td></tr></table></div></address></body></html>
