/usr/share/qt5/doc/qtdoc/threads-technologies.html is in qt5-doc-html 5.2.1-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 | <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.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" />
<!-- threads.qdoc -->
<title>Multithreading Technologies in Qt | QtDoc 5.2</title>
<link rel="stylesheet" type="text/css" href="style/offline.css" />
</head>
<body>
<div class="header" id="qtdocheader">
<div class="main">
<div class="main-rounded">
<div class="navigationbar">
<ul>
<li><a href="index.html">Qt 5.2</a></li>
<li>Multithreading Technologies in Qt</li>
<li id="buildversion">
Qt 5.2.1 Reference Documentation</li>
</ul>
</div>
</div>
<div class="content">
<div class="line">
<div class="content mainContent">
<link rel="prev" href="threads.html" />
<link rel="next" href="threads-synchronizing.html" />
<p class="naviNextPrevious headerNavi">
<a class="prevPage" href="threads.html">Thread Support in Qt</a>
<a class="nextPage" href="threads-synchronizing.html">Synchronizing Threads</a>
</p><p/>
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#qthread-low-level-api-with-optional-event-loops">QThread: Low-Level API with Optional Event Loops</a></li>
<li class="level1"><a href="#qthreadpool-and-qrunnable-reusing-threads">QThreadPool and QRunnable: Reusing Threads</a></li>
<li class="level1"><a href="#qt-concurrent-using-a-high-level-api">Qt Concurrent: Using a High-level API</a></li>
<li class="level1"><a href="#workerscript-threading-in-qml">WorkerScript: Threading in QML</a></li>
<li class="level1"><a href="#choosing-an-appropriate-approach">Choosing an Appropriate Approach</a></li>
<li class="level2"><a href="#comparison-of-solutions">Comparison of Solutions</a></li>
<li class="level2"><a href="#example-use-cases">Example Use Cases</a></li>
</ul>
</div>
<h1 class="title">Multithreading Technologies in Qt</h1>
<span class="subtitle"></span>
<!-- $$$threads-technologies.html-description -->
<div class="descr"> <a name="details"></a>
<p>Qt offers many classes and functions for working with threads. Below are four different approaches that Qt programmers can use to implement multithreaded applications.</p>
<a name="qthread-low-level-api-with-optional-event-loops"></a>
<h2>QThread: Low-Level API with Optional Event Loops</h2>
<p><a href="../qtcore/qthread.html">QThread</a> is the foundation of all thread control in Qt. Each <a href="../qtcore/qthread.html">QThread</a> instance represents and controls one thread.</p>
<p><a href="../qtcore/qthread.html">QThread</a> can either be instantiated directly or subclassed. Instantiating a <a href="../qtcore/qthread.html">QThread</a> provides a parallel event loop, allowing <a href="../qtcore/qobject.html">QObject</a> slots to be invoked in a secondary thread. Subclassing a <a href="../qtcore/qthread.html">QThread</a> allows the application to initialize the new thread before starting its event loop, or to run parallel code without an event loop.</p>
<p>See the <a href="../qtcore/qthread.html">QThread class reference</a> and the <a href="examples-threadandconcurrent.html">threading examples</a> for demonstrations on how to use <a href="../qtcore/qthread.html">QThread</a>.</p>
<a name="qthreadpool-and-qrunnable-reusing-threads"></a>
<h2>QThreadPool and QRunnable: Reusing Threads</h2>
<p>Creating and destroying threads frequently can be expensive. To reduce this overhead, existing threads can be reused for new tasks. <a href="../qtcore/qthreadpool.html">QThreadPool</a> is a collection of reuseable QThreads.</p>
<p>To run code in one of a <a href="../qtcore/qthreadpool.html">QThreadPool</a>'s threads, reimplement <a href="../qtcore/qrunnable.html#run">QRunnable::run</a>() and instantiate the subclassed <a href="../qtcore/qrunnable.html">QRunnable</a>. Use <a href="../qtcore/qthreadpool.html#start">QThreadPool::start</a>() to put the <a href="../qtcore/qrunnable.html">QRunnable</a> in the <a href="../qtcore/qthreadpool.html">QThreadPool</a>'s run queue. When a thread becomes available, the code within <a href="../qtcore/qrunnable.html#run">QRunnable::run</a>() will execute in that thread.</p>
<p>Each Qt application has a global thread pool, which is accessible through <a href="../qtcore/qthreadpool.html#globalInstance">QThreadPool::globalInstance</a>(). This global thread pool automatically maintains an optimal number of threads based on the number of cores in the CPU. However, a separate <a href="../qtcore/qthreadpool.html">QThreadPool</a> can be created and managed explicitly.</p>
<a name="qt-concurrent-using-a-high-level-api"></a>
<h2>Qt Concurrent: Using a High-level API</h2>
<p>The <a href="../qtconcurrent/qtconcurrent-index.html">Qt Concurrent</a> module provides high-level functions that deal with some common parallel computation patterns: map, filter, and reduce. Unlike using <a href="../qtcore/qthread.html">QThread</a> and <a href="../qtcore/qrunnable.html">QRunnable</a>, these functions never require the use of <a href="threads-synchronizing.html#low-level-synchronization-primitives">low-level threading primitives</a> such as mutexes or semaphores. Instead, they return a <a href="../qtcore/qfuture.html">QFuture</a> object which can be used to retrieve the functions' results when they are ready. <a href="../qtcore/qfuture.html">QFuture</a> can also be used to query computation progress and to pause/resume/cancel the computation. For convenience, <a href="../qtcore/qfuturewatcher.html">QFutureWatcher</a> enables interactions with <a href="../qtcore/qfuture.html">QFuture</a>s via signals and slots.</p>
<p><a href="../qtconcurrent/qtconcurrent-index.html">Qt Concurrent</a>'s map, filter and reduce algorithms automatically distribute computation across all available processor cores, so applications written today will continue to scale when deployed later on a system with more cores.</p>
<p>This module also provides the <a href="../qtconcurrent/qtconcurrent.html#run">QtConcurrent::run</a>() function, which can run any function in another thread. However, <a href="../qtconcurrent/qtconcurrent.html#run">QtConcurrent::run</a>() only supports a subset of features available to the map, filter and reduce functions. The <a href="../qtcore/qfuture.html">QFuture</a> can be used to retrieve the function's return value and to check if the thread is running. However, a call to <a href="../qtconcurrent/qtconcurrent.html#run">QtConcurrent::run</a>() uses one thread only, cannot be paused/resumed/canceled, and cannot be queried for progress.</p>
<p>See the <a href="../qtconcurrent/qtconcurrent-index.html">Qt Concurrent</a> module documentation for details on the individual functions.</p>
<a name="workerscript-threading-in-qml"></a>
<h2>WorkerScript: Threading in QML</h2>
<p>The <a href="../qtqml/qml-qtquick-workerscript.html">WorkerScript</a> QML type lets JavaScript code run in parallel with the GUI thread.</p>
<p>Each <a href="../qtqml/qml-qtquick-workerscript.html">WorkerScript</a> instance can have one <tt>.js</tt> script attached to it. When <a href="../qtqml/qml-qtquick-workerscript.html#sendMessage-method">WorkerScript::sendMessage</a>() is called, the script will run in a separate thread (and a separate <a href="../qtqml/qqmlcontext.html">QML context</a>). When the script finishes running, it can send a reply back to the GUI thread which will invoke the WorkerScript::onMessage() signal handler.</p>
<p>Using a <a href="../qtqml/qml-qtquick-workerscript.html">WorkerScript</a> is similar to using a worker <a href="../qtcore/qobject.html">QObject</a> that has been moved to another thread. Data is transferred between threads via signals.</p>
<p>See the <a href="../qtqml/qml-qtquick-workerscript.html">WorkerScript</a> documentation for details on how to implement the script, and for a list of data types that can be passed between threads.</p>
<a name="choosing-an-appropriate-approach"></a>
<h2>Choosing an Appropriate Approach</h2>
<p>As demonstrated above, Qt provides different solutions for developing threaded applications. The right solution for a given application depends on the purpose of the new thread and the thread's lifetime. Below is a comparison of Qt's threading technologies, followed by recommended solutions for some example use cases.</p>
<a name="comparison-of-solutions"></a>
<h3>Comparison of Solutions</h3>
<table class="generic">
<thead><tr class="qt-style"><th >Feature</th><th ><a href="../qtcore/qthread.html">QThread</a></th><th ><a href="../qtcore/qrunnable.html">QRunnable</a> and <a href="../qtcore/qthreadpool.html">QThreadPool</a></th><th ><a href="../qtconcurrent/qtconcurrent.html#run">QtConcurrent::run</a>()</th><th >Qt Concurrent (Map, Filter, Reduce)</th><th ><a href="../qtqml/qml-qtquick-workerscript.html">WorkerScript</a></th></tr></thead>
<tr valign="top" class="odd"><td >API</td><td >C++</td><td >C++</td><td >C++</td><td >C++</td><td >QML</td></tr>
<tr valign="top" class="even"><td >Thread priority can be specified</td><td >Yes</td><td >Yes</td><td ></td><td ></td><td ></td></tr>
<tr valign="top" class="odd"><td >Thread can run an event loop</td><td >Yes</td><td ></td><td ></td><td ></td><td ></td></tr>
<tr valign="top" class="even"><td >Thread can receive data updates through signals</td><td >Yes (received by a worker <a href="../qtcore/qobject.html">QObject</a>)</td><td ></td><td ></td><td ></td><td >Yes (received by <a href="../qtqml/qml-qtquick-workerscript.html">WorkerScript</a>)</td></tr>
<tr valign="top" class="odd"><td >Thread can be controlled using signals</td><td >Yes (received by <a href="../qtcore/qthread.html">QThread</a>)</td><td ></td><td ></td><td >Yes (received by <a href="../qtcore/qfuturewatcher.html">QFutureWatcher</a>)</td><td ></td></tr>
<tr valign="top" class="even"><td >Thread can be monitored through a <a href="../qtcore/qfuture.html">QFuture</a></td><td ></td><td ></td><td >Partially</td><td >Yes</td><td ></td></tr>
<tr valign="top" class="odd"><td >Built-in ability to pause/resume/cancel</td><td ></td><td ></td><td ></td><td >Yes</td><td ></td></tr>
</table>
<a name="example-use-cases"></a>
<h3>Example Use Cases</h3>
<table class="generic">
<thead><tr class="qt-style"><th >Lifetime of thread</th><th >Operation</th><th >Solution</th></tr></thead>
<tr valign="top" class="odd"><td >One call</td><td >Run a new linear function within another thread, optionally with progress updates during the run.</td><td >Qt provides different solutions:<ul>
<li>Place the function in a reimplementation of <a href="../qtcore/qthread.html#run">QThread::run</a>() and start the <a href="../qtcore/qthread.html">QThread</a>. Emit signals to update progress. OR</li>
<li>Place the function in a reimplementation of <a href="../qtcore/qrunnable.html#run">QRunnable::run</a>() and add the <a href="../qtcore/qrunnable.html">QRunnable</a> to a <a href="../qtcore/qthreadpool.html">QThreadPool</a>. Write to a <a href="threads-synchronizing.html">thread-safe variable</a> to update progress. OR</li>
<li>Run the function using <a href="../qtconcurrent/qtconcurrent.html#run">QtConcurrent::run</a>(). Write to a <a href="threads-synchronizing.html">thread-safe variable</a> to update progress.</li>
</ul>
</td></tr>
<tr valign="top" class="even"><td >One call</td><td >Run an existing function within another thread and get its return value.</td><td >Run the function using <a href="../qtconcurrent/qtconcurrent.html#run">QtConcurrent::run</a>(). Have a <a href="../qtcore/qfuturewatcher.html">QFutureWatcher</a> emit the <a href="../qtcore/qfuturewatcher.html#finished">finished()</a> signal when the function has returned, and call <a href="../qtcore/qfuturewatcher.html#result">QFutureWatcher::result</a>() to get the function's return value.</td></tr>
<tr valign="top" class="odd"><td >One call</td><td >Perform an operation on all items of a container, using all available cores. For example, producing thumbnails from a list of images.</td><td >Use Qt Concurrent's <a href="../qtconcurrent/qtconcurrent.html#filter">filter()</a> function to select container elements, and the <a href="../qtconcurrent/qtconcurrent.html#map">map()</a> function to apply an operation to each element. To fold the output into a single result, use <a href="../qtconcurrent/qtconcurrent.html#filteredReduced">filteredReduced()</a> and <a href="../qtconcurrent/qtconcurrent.html#mappedReduced">mappedReduced()</a> instead.</td></tr>
<tr valign="top" class="even"><td >One call/Permanent</td><td >Perfrom a long computation in a pure QML application, and update the GUI when the results are ready.</td><td >Place the computation code in a <tt>.js</tt> script and attach it to a <a href="../qtqml/qml-qtquick-workerscript.html">WorkerScript</a> instance. Call <a href="../qtqml/qml-qtquick-workerscript.html#sendMessage-method">sendMessage()</a> to start the computation in a new thread. Let the script call <a href="../qtqml/qml-qtquick-workerscript.html#sendMessage-method">WorkerScript::sendMessage</a>() too, to pass the result back to the GUI thread. Handle the result in <a href="../qtqml/qml-qtquick-workerscript.html#onMessage-signal">onMessage</a> and update the GUI there.</td></tr>
<tr valign="top" class="odd"><td >Permanent</td><td >Have an object living in another thread that can perform different tasks upon request and/or can receive new data to work with.</td><td >Subclass a <a href="../qtcore/qobject.html">QObject</a> to create a worker. Instantiate this worker object and a <a href="../qtcore/qthread.html">QThread</a>. Move the worker to the new thread. Send commands or data to the worker object over queued signal-slot connections.</td></tr>
<tr valign="top" class="even"><td >Permanent</td><td >Repeatedly perform an expensive operation in another thread, where the thread does not need to receive any signals or events.</td><td >Write the infinite loop directly within a reimplementation of <a href="../qtcore/qthread.html#run">QThread::run</a>(). Start the thread without an event loop. Let the thread emit signals to send data back to the GUI thread.</td></tr>
</table>
</div>
<!-- @@@threads-technologies.html -->
<p class="naviNextPrevious footerNavi">
<a class="prevPage" href="threads.html">Thread Support in Qt</a>
<a class="nextPage" href="threads-synchronizing.html">Synchronizing Threads</a>
</p>
</div>
</div>
</div>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2013 Digia Plc and/or its
subsidiaries. Documentation contributions included herein are the copyrights of
their respective owners.<br> 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.<br> Digia, Qt and their respective logos are trademarks of Digia Plc in Finland and/or other countries worldwide. All other trademarks are property
of their respective owners. </p>
</div>
</body>
</html>
|