qt5-doc-html 5.2.1-1 / usr / share / qt5 / doc / qtdoc / threads-reentrancy.html

This file is indexed.

/usr/share/qt5/doc/qtdoc/threads-reentrancy.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
<?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>Reentrancy and Thread-Safety | 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>Reentrancy and Thread-Safety</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-synchronizing.html" />
  <link rel="next" href="threads-qobject.html" />
<p class="naviNextPrevious headerNavi">
<a class="prevPage" href="threads-synchronizing.html">Synchronizing Threads</a>
<a class="nextPage" href="threads-qobject.html">Threads and QObjects</a>
</p><p/>
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#reentrancy">Reentrancy</a></li>
<li class="level1"><a href="#thread-safety">Thread-Safety</a></li>
<li class="level1"><a href="#notes-on-qt-classes">Notes on Qt Classes</a></li>
</ul>
</div>
<h1 class="title">Reentrancy and Thread-Safety</h1>
<span class="subtitle"></span>
<!-- $$$threads-reentrancy.html-description -->
<div class="descr"> <a name="details"></a>
<a name="reentrant"></a><a name="thread-safe"></a><p>Throughout the documentation, the terms <i>reentrant</i> and <i>thread-safe</i> are used to mark classes and functions to indicate how they can be used in multithread applications:</p>
<ul>
<li>A <i>thread-safe</i> function can be called simultaneously from multiple threads, even when the invocations use shared data, because all references to the shared data are serialized.</li>
<li>A <i>reentrant</i> function can also be called simultaneously from multiple threads, but only if each invocation uses its own data.</li>
</ul>
<p>Hence, a <i>thread-safe</i> function is always <i>reentrant</i>, but a <i>reentrant</i> function is not always <i>thread-safe</i>.</p>
<p>By extension, a class is said to be <i>reentrant</i> if its member functions can be called safely from multiple threads, as long as each thread uses a <i>different</i> instance of the class. The class is <i>thread-safe</i> if its member functions can be called safely from multiple threads, even if all the threads use the <i>same</i> instance of the class.</p>
<p><b>Note: </b>Qt classes are only documented as <i>thread-safe</i> if they are intended to be used by multiple threads. If a function is not marked as thread-safe or reentrant, it should not be used from different threads. If a class is not marked as thread-safe or reentrant then a specific instance of that class should not be accessed from different threads.</p><a name="reentrancy"></a>
<h2>Reentrancy</h2>
<p>C++ classes are often reentrant, simply because they only access their own member data. Any thread can call a member function on an instance of a reentrant class, as long as no other thread can call a member function on the <i>same</i> instance of the class at the same time. For example, the <tt>Counter</tt> class below is reentrant:</p>
<pre class="cpp"><span class="keyword">class</span> Counter
{
<span class="keyword">public</span>:
    Counter() { n <span class="operator">=</span> <span class="number">0</span>; }

    <span class="type">void</span> increment() { <span class="operator">+</span><span class="operator">+</span>n; }
    <span class="type">void</span> decrement() { <span class="operator">-</span><span class="operator">-</span>n; }
    <span class="type">int</span> value() <span class="keyword">const</span> { <span class="keyword">return</span> n; }

<span class="keyword">private</span>:
    <span class="type">int</span> n;
};</pre>
<p>The class isn't thread-safe, because if multiple threads try to modify the data member <tt>n</tt>, the result is undefined. This is because the <tt>++</tt> and <tt>--</tt> operators aren't always atomic. Indeed, they usually expand to three machine instructions:</p>
<ol class="1">
<li>Load the variable's value in a register.</li>
<li>Increment or decrement the register's value.</li>
<li>Store the register's value back into main memory.</li>
</ol>
<p>If thread A and thread B load the variable's old value simultaneously, increment their register, and store it back, they end up overwriting each other, and the variable is incremented only once!</p>
<a name="thread-safety"></a>
<h2>Thread-Safety</h2>
<p>Clearly, the access must be serialized: Thread A must perform steps 1, 2, 3 without interruption (atomically) before thread B can perform the same steps; or vice versa. An easy way to make the class thread-safe is to protect all access to the data members with a <a href="../qtcore/qmutex.html">QMutex</a>:</p>
<pre class="cpp"><span class="keyword">class</span> Counter
{
<span class="keyword">public</span>:
    Counter() { n <span class="operator">=</span> <span class="number">0</span>; }

    <span class="type">void</span> increment() { <span class="type"><a href="../qtcore/qmutexlocker.html">QMutexLocker</a></span> locker(<span class="operator">&amp;</span>mutex); <span class="operator">+</span><span class="operator">+</span>n; }
    <span class="type">void</span> decrement() { <span class="type"><a href="../qtcore/qmutexlocker.html">QMutexLocker</a></span> locker(<span class="operator">&amp;</span>mutex); <span class="operator">-</span><span class="operator">-</span>n; }
    <span class="type">int</span> value() <span class="keyword">const</span> { <span class="type"><a href="../qtcore/qmutexlocker.html">QMutexLocker</a></span> locker(<span class="operator">&amp;</span>mutex); <span class="keyword">return</span> n; }

<span class="keyword">private</span>:
    <span class="keyword">mutable</span> <span class="type"><a href="../qtcore/qmutex.html">QMutex</a></span> mutex;
    <span class="type">int</span> n;
};</pre>
<p>The <a href="../qtcore/qmutexlocker.html">QMutexLocker</a> class automatically locks the mutex in its constructor and unlocks it when the destructor is invoked, at the end of the function. Locking the mutex ensures that access from different threads will be serialized. The <tt>mutex</tt> data member is declared with the <tt>mutable</tt> qualifier because we need to lock and unlock the mutex in <tt>value()</tt>, which is a const function.</p>
<a name="notes-on-qt-classes"></a>
<h2>Notes on Qt Classes</h2>
<p>Many Qt classes are <i>reentrant</i>, but they are not made <i>thread-safe</i>, because making them thread-safe would incur the extra overhead of repeatedly locking and unlocking a <a href="../qtcore/qmutex.html">QMutex</a>. For example, <a href="../qtcore/qstring.html">QString</a> is reentrant but not thread-safe. You can safely access <i>different</i> instances of <a href="../qtcore/qstring.html">QString</a> from multiple threads simultaneously, but you can't safely access the <i>same</i> instance of <a href="../qtcore/qstring.html">QString</a> from multiple threads simultaneously (unless you protect the accesses yourself with a <a href="../qtcore/qmutex.html">QMutex</a>).</p>
<p>Some Qt classes and functions are thread-safe. These are mainly the thread-related classes (e.g&#x2e; <a href="../qtcore/qmutex.html">QMutex</a>) and fundamental functions (e.g&#x2e; <a href="../qtcore/qcoreapplication.html#postEvent">QCoreApplication::postEvent</a>()).</p>
<p><b>Note: </b>Terminology in the multithreading domain isn't entirely standardized. POSIX uses definitions of reentrant and thread-safe that are somewhat different for its C APIs. When using other object-oriented C++ class libraries with Qt, be sure the definitions are understood.</p></div>
<!-- @@@threads-reentrancy.html -->
<p class="naviNextPrevious footerNavi">
<a class="prevPage" href="threads-synchronizing.html">Synchronizing Threads</a>
<a class="nextPage" href="threads-qobject.html">Threads and QObjects</a>
</p>
        </div>
       </div>
   </div>
   </div>
</div>
<div class="footer">
   <p>
   <acronym title="Copyright">&copy;</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>

APT Browse - Built by Thomas Orozco.