<?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>