<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- qdoc-manual-contextcmds.qdoc -->
<title>Thread Support | QDoc Manual 5.9</title>
<link rel="stylesheet" type="text/css" href="style/offline-simple.css" />
<script type="text/javascript">
document.getElementsByTagName("link").item(0).setAttribute("href", "style/offline.css");
// loading style sheet breaks anchors that were jumped to before
// so force jumping to anchor again
setTimeout(function() {
var anchor = location.hash;
// need to jump to different anchor first (e.g. none)
location.hash = "#";
setTimeout(function() {
location.hash = anchor;
}, 0);
}, 0);
</script>
</head>
<body>
<div class="header" id="qtdocheader">
<div class="main">
<div class="main-rounded">
<div class="navigationbar">
<table><tr>
<td >Qt 5.9</td><td ><a href="qdoc-index.html">QDoc Manual</a></td><td >Thread Support</td></tr></table><table class="buildversion"><tr>
<td id="buildversion" width="100%" align="right">Qt 5.9.4 Reference Documentation</td>
</tr></table>
</div>
</div>
<div class="content">
<div class="line">
<div class="content mainContent">
<link rel="prev" href="16-qdoc-commands-status.html" />
<link rel="next" href="18-qdoc-commands-relating.html" />
<p class="naviNextPrevious headerNavi">
<a class="prevPage" href="16-qdoc-commands-status.html">Status</a>
<span class="naviSeparator"> ◦ </span>
<a class="nextPage" href="18-qdoc-commands-relating.html">Relating Things</a>
</p><p/>
<div class="sidebar">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#example">Example</a></li>
<li class="level1"><a href="#commands">Commands</a></li>
<li class="level2"><a href="#threadsafe">\threadsafe</a></li>
<li class="level2"><a href="#reentrant">\reentrant</a></li>
<li class="level2"><a href="#nonreentrant">\nonreentrant</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">Thread Support</h1>
<span class="subtitle"></span>
<!-- $$$17-qdoc-commands-thread.html-description -->
<div class="descr"> <a name="details"></a>
<p>The thread support commands are for specifying the level of support for multithreaded programming in a class or function. There are three levels of support: <code>threadsafe</code>, <code>reentrant</code> and <code>nonreentrant</code>.</p>
<p>The default is <code>nonreentrant</code> which means that the associated class or function cannot be called by multiple threads. <code>Reentrant</code> and <code>threadsafe</code> are levels primarily used for classes.</p>
<p><code>Reentrant</code> means that all the functions in the referenced class can be called simultaneously by multiple threads, provided that each invocation of the functions reference unique data. While <code>threadsafe</code> means that all the functions in the referenced class can be called simultaneously by multiple threads even when each invocation references shared data.</p>
<p>When a class is marked <a href="17-qdoc-commands-thread.html#reentrant-command">\reentrant</a> or <a href="17-qdoc-commands-thread.html#threadsafe-command">\threadsafe</a>, functions in that class can be marked <code>nonreentrant</code> using the <a href="17-qdoc-commands-thread.html#nonreentrant-command">\nonreentrant</a> command.</p>
<a name="example"></a>
<h2 id="example">Example</h2>
<a name="reentrant-example"></a><pre class="cpp">
\beginqdoc
\<span class="keyword">class</span> <span class="type">QLocale</span>
\brief The <span class="type">QLocale</span> <span class="keyword">class</span> converts between numbers and their
string representations in various languages<span class="operator">.</span>
\reentrant
\ingroup i18n
\ingroup text
<span class="type">QLocale</span> is initialized with a language<span class="operator">/</span>country pair in its
constructor and offers number<span class="operator">-</span>to<span class="operator">-</span>string and string<span class="operator">-</span>to<span class="operator">-</span>number
conversion functions similar to those in <span class="type">QString</span><span class="operator">.</span>
<span class="operator">.</span><span class="operator">.</span><span class="operator">.</span>
\nonreentrant
Sets the global <span class="keyword">default</span> locale to \a locale<span class="operator">.</span> These values are
used when a <span class="type">QLocale</span> object is constructed with no
arguments<span class="operator">.</span> If <span class="keyword">this</span> function is <span class="keyword">not</span> called<span class="operator">,</span> the system<span class="char">'s locale
is used.
\warning In a multithreaded application, the default locale
should be set at application startup, before any non-GUI
threads are created.
\sa system(), c()
\endqdoc
void QLocale::setDefault(const QLocale &locale)
{
default_d = locale.d;
}
</span>
</pre>
<p>QDoc renders this as:</p>
<blockquote> <h1><center>QLocale Class Reference</center></h1>
<p>The QLocale class converts between numbers and their string representations in various languages. More...</p>
<pre class="cpp">
<span class="preprocessor">#include <QLocale></span>
</pre>
<p><b>Note:</b> All the functions in this class are <a href="17-qdoc-commands-thread.html#reentrant">reentrant</a>, except setDefault().</p>
<p>...</p>
<hr />
<h2>Member Type Documentation</h2>
<p>...</p>
<h3>void QLocale::setDefault ( const QLocale & locale ) </h3>
<p>Sets the global default locale to locale. These values are used when a QLocale object is constructed with no arguments. If this function is not called, the system's locale is used.</p>
<p><b>Warning:</b> In a multithreaded application, the default locale should be set at application startup, before any non-GUI threads are created.</p>
<p><b>Warning:</b> This function is not reentrant.</p>
<p>See also system() and c().</p>
<p>...</p>
</blockquote>
<p>As shown above, QDoc generates a notification when a class is declared reentrant, and lists the exceptions (the declared nonreentrant functions). A link to the general documentation on <a href="17-qdoc-commands-thread.html#reentrant">reentrancy and thread-safety</a> is included. In addition a warning, "<b>Warning</b>: This function is not reentrant.", is generated in the nonreentrant functions' documentation.</p>
<p>QDoc will generate the same notification and warnings when a class is declared threadsafe.</p>
<p>For more information see the general documentation on <a href="17-qdoc-commands-thread.html#reentrant">reentrancy and thread-safety</a>.</p>
<a name="commands"></a>
<h2 id="commands">Commands</h2>
<a name="threadsafe-command"></a><a name="threadsafe"></a>
<h3 >\threadsafe</h3>
<p>The \threadsafe command includes a line in the documentation to indicate that the associated class or function is <i>threadsafe</i> and can be called simultaneously by multiple threads, even when separate invocations reference shared data.</p>
<p>The command must stand on its own line.</p>
<p>The documentation generated from this command will be similar to the what is generated for the <a href="17-qdoc-commands-thread.html#reentrant-command">\reentrant</a> command. See the example above in the <a href="17-qdoc-commands-thread.html#reentrant-example">introduction</a>.</p>
<p>See also <a href="17-qdoc-commands-thread.html#reentrant-command">\reentrant</a> and <a href="17-qdoc-commands-thread.html#nonreentrant-command">\nonreentrant</a>.</p>
<a name="reentrant-command"></a><a name="reentrant"></a>
<h3 >\reentrant</h3>
<p>The \reentrant command indicates that the associated class or function can be called simultaneously by multiple threads, provided that each invocation references its own data. See the <a href="17-qdoc-commands-thread.html#reentrant-example">example</a> above.</p>
<p>The command must stand on its own line.</p>
<p>See also <a href="17-qdoc-commands-thread.html#nonreentrant-command">\nonreentrant</a> and <a href="17-qdoc-commands-thread.html#threadsafe-command">\threadsafe</a>.</p>
<a name="nonreentrant-command"></a><a name="nonreentrant"></a>
<h3 >\nonreentrant</h3>
<p>The \nonreentrant command indicates that the associated class or function cannot be called by multiple threads. Nonreentrant is the default case.</p>
<p>The command must stand on its own line.</p>
<p>When a class is marked <a href="17-qdoc-commands-thread.html#reentrant-command">\reentrant</a> or <a href="17-qdoc-commands-thread.html#threadsafe-command">\threadsafe</a>, functions in that class can be marked <code>nonreentrant</code> using this command in the <a href="13-qdoc-commands-topics.html#fn-command">\fn</a> comment of the functions to be excluded.</p>
<p>See also <a href="17-qdoc-commands-thread.html#reentrant-command">\reentrant</a> and <a href="17-qdoc-commands-thread.html#threadsafe-command">\threadsafe</a>.</p>
</div>
<!-- @@@17-qdoc-commands-thread.html -->
<p class="naviNextPrevious footerNavi">
<a class="prevPage" href="16-qdoc-commands-status.html">Status</a>
<span class="naviSeparator"> ◦ </span>
<a class="nextPage" href="18-qdoc-commands-relating.html">Relating Things</a>
</p>
</div>
</div>
</div>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2017 The Qt Company Ltd.
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> 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. </p>
</div>
</body>
</html>
