<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- qglobalstatic.qdoc -->
<title>QGlobalStatic Class | Qt Core 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="qtcore-index.html">Qt Core</a></td><td ><a href="qtcore-module.html">C++ Classes</a></td><td >QGlobalStatic</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">
<div class="sidebar">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#public-types">Public Types</a></li>
<li class="level1"><a href="#public-functions">Public Functions</a></li>
<li class="level1"><a href="#macros">Macros</a></li>
<li class="level1"><a href="#details">Detailed Description</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">QGlobalStatic Class</h1>
<!-- $$$QGlobalStatic-brief -->
<p>The <a href="qglobalstatic.html">QGlobalStatic</a> class is used to implement a global static object <a href="#details">More...</a></p>
<!-- @@@QGlobalStatic -->
<div class="table"><table class="alignedsummary">
<tr><td class="memItemLeft rightAlign topAlign"> Header:</td><td class="memItemRight bottomAlign"> <span class="preprocessor">#include <QGlobalStatic></span>
</td></tr><tr><td class="memItemLeft rightAlign topAlign"> qmake:</td><td class="memItemRight bottomAlign"> QT += core</td></tr><tr><td class="memItemLeft rightAlign topAlign"> Since:</td><td class="memItemRight bottomAlign"> Qt 5.1</td></tr></table></div><ul>
<li><a href="qglobalstatic-members.html">List of all members, including inherited members</a></li>
<li><a href="qglobalstatic-obsolete.html">Obsolete members</a></li>
</ul>
<p><b>Note:</b> All functions in this class are thread-safe.</p>
<a name="public-types"></a>
<h2 id="public-types">Public Types</h2>
<div class="table"><table class="alignedsummary">
<tr><td class="memItemLeft rightAlign topAlign"> typedef </td><td class="memItemRight bottomAlign"><b><a href="qglobalstatic.html#Type-typedef">Type</a></b></td></tr>
</table></div>
<a name="public-functions"></a>
<h2 id="public-functions">Public Functions</h2>
<div class="table"><table class="alignedsummary">
<tr><td class="memItemLeft rightAlign topAlign"> bool </td><td class="memItemRight bottomAlign"><b><a href="qglobalstatic.html#exists">exists</a></b>() const</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> bool </td><td class="memItemRight bottomAlign"><b><a href="qglobalstatic.html#isDestroyed">isDestroyed</a></b>() const</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> </td><td class="memItemRight bottomAlign"><b><a href="qglobalstatic.html#operator-Type--2a">operator Type *</a></b>()</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> Type &</td><td class="memItemRight bottomAlign"><b><a href="qglobalstatic.html#operator-2a">operator*</a></b>()</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> Type *</td><td class="memItemRight bottomAlign"><b><a href="qglobalstatic.html#operator--gt">operator-></a></b>()</td></tr>
</table></div>
<a name="macros"></a>
<h2 id="macros">Macros</h2>
<div class="table"><table class="alignedsummary">
<tr><td class="memItemLeft rightAlign topAlign"> </td><td class="memItemRight bottomAlign"><b><a href="qglobalstatic.html#Q_GLOBAL_STATIC">Q_GLOBAL_STATIC</a></b>(<i>Type</i>, <i>VariableName</i>)</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> </td><td class="memItemRight bottomAlign"><b><a href="qglobalstatic.html#Q_GLOBAL_STATIC_WITH_ARGS">Q_GLOBAL_STATIC_WITH_ARGS</a></b>(<i>Type</i>, <i>VariableName</i>, <i>Arguments</i>)</td></tr>
</table></div>
<a name="details"></a>
<!-- $$$QGlobalStatic-description -->
<div class="descr">
<h2 id="details">Detailed Description</h2>
<p>The <a href="qglobalstatic.html">QGlobalStatic</a> class is used to implement a global static object</p>
<p>The <a href="qglobalstatic.html">QGlobalStatic</a> class is the front-end API exported when <a href="qglobalstatic.html#Q_GLOBAL_STATIC">Q_GLOBAL_STATIC</a>() is used. See the documentation for the macro for a discussion on when to use it and its requirements.</p>
<p>Normally, you will never use this class directly, but instead you will use the <a href="qglobalstatic.html#Q_GLOBAL_STATIC">Q_GLOBAL_STATIC</a>() or <a href="qglobalstatic.html#Q_GLOBAL_STATIC_WITH_ARGS">Q_GLOBAL_STATIC_WITH_ARGS</a>() macros, as follows:</p>
<pre class="cpp">
Q_GLOBAL_STATIC(MyType<span class="operator">,</span> staticType)
</pre>
<p>The above example creates an object of type <a href="qglobalstatic.html">QGlobalStatic</a> called <code>staticType</code>. After the above declaration, the <code>staticType</code> object may be used as if it were a pointer, guaranteed to be initialized exactly once. In addition to the use as a pointer, the object offers two methods to determine the current status of the global: <a href="qglobalstatic.html#exists">exists</a>() and <a href="qglobalstatic.html#isDestroyed">isDestroyed</a>().</p>
</div>
<p><b>See also </b><a href="qglobalstatic.html#Q_GLOBAL_STATIC">Q_GLOBAL_STATIC</a>() and <a href="qglobalstatic.html#Q_GLOBAL_STATIC_WITH_ARGS">Q_GLOBAL_STATIC_WITH_ARGS</a>().</p>
<!-- @@@QGlobalStatic -->
<div class="types">
<h2>Member Type Documentation</h2>
<!-- $$$Type -->
<h3 class="fn" id="Type-typedef"><a name="Type-typedef"></a>typedef QGlobalStatic::<span class="name">Type</span></h3>
<p>This type is equivalent to the <code>Type</code> parameter passed to the <a href="qglobalstatic.html#Q_GLOBAL_STATIC">Q_GLOBAL_STATIC</a>() or <a href="qglobalstatic.html#Q_GLOBAL_STATIC_WITH_ARGS">Q_GLOBAL_STATIC_WITH_ARGS</a>() macros. It is used in the return types of some functions.</p>
<!-- @@@Type -->
</div>
<div class="func">
<h2>Member Function Documentation</h2>
<!-- $$$exists[overload1]$$$exists -->
<h3 class="fn" id="exists"><a name="exists"></a><span class="type">bool</span> QGlobalStatic::<span class="name">exists</span>() const</h3>
<p>This function returns <code>true</code> if the global static object has already completed initialization (that is, if the constructor for the type has already returned). In specific, note that this function returns <code>false</code> if the initialization is still in progress.</p>
<p>Once this function has returned true once, it will never return false again until either the program is restarted or the plugin or library containing the global static is unloaded and reloaded.</p>
<p>This function is safe to call at any point in the program execution: it cannot fail and cannot cause a deadlock. Additionally, it will not cause the contents to be created if they have not yet been created.</p>
<p>This function is useful if one can determine the initial conditions of the global static object and would prefer to avoid a possibly expensive construction operation.</p>
<p>For example, in the following code sample, this function is used to short-circuit the creation of the global static called <code>globalState</code> and returns a default value:</p>
<pre class="cpp">
Q_GLOBAL_STATIC(MyType<span class="operator">,</span> globalState)
<span class="type"><a href="qstring.html">QString</a></span> someState()
{
<span class="keyword">if</span> (globalState<span class="operator">.</span>exists())
<span class="keyword">return</span> globalState<span class="operator">-</span><span class="operator">></span>someState;
<span class="keyword">return</span> <span class="type"><a href="qstring.html">QString</a></span>();
}
</pre>
<p><b>Thread-safety notice:</b> this function is thread-safe in the sense that it may be called from any thread at any time and will always return a valid reply. But due to the non-atomic nature of construction, this function may return false for a short time after the construction has completed.</p>
<p><b>Memory ordering notice:</b> this function does not impose any memory ordering guarantees. That is instead provided by the accessor functions that return the pointer or reference to the contents. If you bypass the accessor functions and attempt to access some global state set by the constructor, be sure to use the correct memory ordering semantics provided by <a href="qatomicint.html">QAtomicInt</a> or <a href="qatomicpointer.html">QAtomicPointer</a>.</p>
<p><b>See also </b><a href="qglobalstatic.html#isDestroyed">isDestroyed</a>().</p>
<!-- @@@exists -->
<!-- $$$isDestroyed[overload1]$$$isDestroyed -->
<h3 class="fn" id="isDestroyed"><a name="isDestroyed"></a><span class="type">bool</span> QGlobalStatic::<span class="name">isDestroyed</span>() const</h3>
<p>This function returns <code>true</code> if the global static object has already completed destruction (that is, if the destructor for the type has already returned). In specific, note that this function returns <code>false</code> if the destruction is still in progress.</p>
<p>Once this function has returned true once, it will never return false again until either the program is restarted or the plugin or library containing the global static is unloaded and reloaded.</p>
<p>This function is safe to call at any point in the program execution: it cannot fail and cannot cause a deadlock. Additionally, it will not cause the contents to be created if they have not yet been created.</p>
<p>This function is useful in code that may be executed at program shutdown, to determine whether the contents may still be accessed or not.</p>
<p><b>See also </b><a href="qglobalstatic.html#exists">exists</a>().</p>
<!-- @@@isDestroyed -->
<!-- $$$operator Type *[overload1]$$$operator Type * -->
<h3 class="fn" id="operator-Type--2a"><a name="operator-Type--2a"></a>QGlobalStatic::<span class="name">operator Type *</span>()</h3>
<p>This function returns the address of the contents of this global static. If the contents have not yet been created, they will be created thread-safely by this function. If the contents have already been destroyed, this function will return a null pointer.</p>
<p>This function can be used, for example, to store the pointer to the contents of the global static in a local variable, thus avoiding multiple calls to the function. The implementation of <a href="qglobalstatic.html#Q_GLOBAL_STATIC">Q_GLOBAL_STATIC</a>() is quite efficient already, but in performance-critical sections it might be useful to help the compiler a little. For example:</p>
<pre class="cpp">
Q_GLOBAL_STATIC(MyType<span class="operator">,</span> globalState)
<span class="type"><a href="qstring.html">QString</a></span> someState()
{
MyType <span class="operator">*</span>state <span class="operator">=</span> globalState;
<span class="keyword">if</span> (<span class="operator">!</span>state) {
<span class="comment">// we're in a post-destruction state</span>
<span class="keyword">return</span> <span class="type"><a href="qstring.html">QString</a></span>();
}
<span class="keyword">if</span> (state<span class="operator">-</span><span class="operator">></span>condition)
<span class="keyword">return</span> state<span class="operator">-</span><span class="operator">></span>value1;
<span class="keyword">else</span>
<span class="keyword">return</span> state<span class="operator">-</span><span class="operator">></span>value2;
}
</pre>
<p><b>See also </b><a href="qglobalstatic.html#operator--gt">operator-></a>() and <a href="qglobalstatic.html#operator-2a">operator*</a>().</p>
<!-- @@@operator Type * -->
<!-- $$$operator*[overload1]$$$operator* -->
<h3 class="fn" id="operator-2a"><a name="operator-2a"></a><span class="type"><a href="qglobalstatic.html#Type-typedef">Type</a></span> &QGlobalStatic::<span class="name">operator*</span>()</h3>
<p>This function returns a reference to the contents of this global static. If the contents have not yet been created, they will be created thread-safely by this function.</p>
<p>This function does not check if the contents have already been destroyed. If this function is called after the object has been destroyed, it will return an invalid reference that must not be used.</p>
<!-- @@@operator* -->
<!-- $$$operator->[overload1]$$$operator-> -->
<h3 class="fn" id="operator--gt"><a name="operator--gt"></a><span class="type"><a href="qglobalstatic.html#Type-typedef">Type</a></span> *QGlobalStatic::<span class="name">operator-></span>()</h3>
<p>This function returns the address of the contents of this global static. If the contents have not yet been created, they will be created thread-safely by this function.</p>
<p>This function does not check if the contents have already been destroyed and will never return null. If this function is called after the object has been destroyed, it will return a dangling pointer that should not be dereferenced.</p>
<!-- @@@operator-> -->
</div>
<div class="macros">
<h2>Macro Documentation</h2>
<!-- $$$Q_GLOBAL_STATIC[overload1]$$$Q_GLOBAL_STATIC -->
<h3 class="fn" id="Q_GLOBAL_STATIC"><a name="Q_GLOBAL_STATIC"></a><span class="name">Q_GLOBAL_STATIC</span>(<i>Type</i>, <i>VariableName</i>)</h3>
<p>Creates a global and static object of type <a href="qglobalstatic.html">QGlobalStatic</a>, of name <i>VariableName</i> and that behaves as a pointer to <i>Type</i>. The object created by Q_GLOBAL_STATIC initializes itself on the first use, which means that it will not increase the application or the library's load time. Additionally, the object is initialized in a thread-safe manner on all platforms.</p>
<p>The typical use of this macro is as follows, in a global context (that is, outside of any function bodies):</p>
<pre class="cpp">
Q_GLOBAL_STATIC(MyType<span class="operator">,</span> staticType)
</pre>
<p>This macro is intended to replace global static objects that are not POD (Plain Old Data, or in C++11 terms, not made of a trivial type), hence the name. For example, the following C++ code creates a global static:</p>
<pre class="cpp">
<span class="keyword">static</span> MyType staticType;
</pre>
<p>Compared to Q_GLOBAL_STATIC, and assuming that <code>MyType</code> is a class or struct that has a constructor, a destructor, or is otherwise non-POD, the above has the following drawbacks:</p>
<ul>
<li>it requires load-time initialization of <code>MyType</code> (that is, the default constructor for <code>MyType</code> is called when the library or application is loaded);</li>
<li>the type will be initialized even if it is never used;</li>
<li>the order of initialization and destruction among different translation units is not determined, leading to possible uses before initialization or after destruction;</li>
<li>if it is found inside a function (that is, not global), it will be initialized on first use, but many current compilers (as of 2013) do not guarantee that the initialization will be thread-safe;</li>
</ul>
<p>The Q_GLOBAL_STATIC macro solves all of the above problems by guaranteeing thread-safe initialization on first use and allowing the user to query for whether the type has already been destroyed, to avoid the use-after-destruction problem (see <a href="qglobalstatic.html#isDestroyed">QGlobalStatic::isDestroyed</a>()).</p>
<a name="constructor-and-destructor"></a>
<h4 >Constructor and Destructor</h4>
<p>For Q_GLOBAL_STATIC, the type <code>Type</code> must be publicly default-constructible and publicly destructible. For <a href="qglobalstatic.html#Q_GLOBAL_STATIC_WITH_ARGS">Q_GLOBAL_STATIC_WITH_ARGS</a>(), there must be a public constructor that matches the arguments passed.</p>
<p>It is not possible to use Q_GLOBAL_STATIC with types that have protected or private default constructors or destructors (for <a href="qglobalstatic.html#Q_GLOBAL_STATIC_WITH_ARGS">Q_GLOBAL_STATIC_WITH_ARGS</a>(), a protected or private constructor matching the arguments). If the type in question has those members as protected, it is possible to overcome the issue by deriving from the type and creating public a constructor and destructor. If the type has them as private, a friend declaration is necessary before deriving.</p>
<p>For example, the following is enough to create <code>MyType</code> based on a previously-defined <code>MyOtherType</code> which has a protected default constructor and/or a protected destructor (or has them as private, but that defines <code>MyType</code> as a friend).</p>
<pre class="cpp">
<span class="keyword">class</span> MyType : <span class="keyword">public</span> MyOtherType { };
Q_GLOBAL_STATIC(MyType<span class="operator">,</span> staticType)
</pre>
<p>No body for <code>MyType</code> is required since the destructor is an implicit member and so is the default constructor if no other constructors are defined. For use with <a href="qglobalstatic.html#Q_GLOBAL_STATIC_WITH_ARGS">Q_GLOBAL_STATIC_WITH_ARGS</a>(), however, a suitable constructor body is necessary:</p>
<pre class="cpp">
<span class="keyword">class</span> MyType : <span class="keyword">public</span> MyOtherType
{
<span class="keyword">public</span>:
MyType(<span class="type">int</span> i) : MyOtherType(i) {}
};
Q_GLOBAL_STATIC_WITH_ARGS(MyType<span class="operator">,</span> staticType<span class="operator">,</span> (<span class="number">42</span>))
</pre>
<p>Alternatively, if the compiler supports C++11 inheriting constructors, one could write:</p>
<pre class="cpp">
<span class="keyword">class</span> MyType : <span class="keyword">public</span> MyOtherType
{
<span class="keyword">public</span>:
<span class="keyword">using</span> MyOtherType<span class="operator">::</span>MyOtherType;
};
Q_GLOBAL_STATIC_WITH_ARGS(MyType<span class="operator">,</span> staticType<span class="operator">,</span> (<span class="number">42</span>))
</pre>
<a name="placement"></a>
<h4 >Placement</h4>
<p>The Q_GLOBAL_STATIC macro creates a type that is necessarily static, at the global scope. It is not possible to place the Q_GLOBAL_STATIC macro inside a function (doing so will result in compilation errors).</p>
<p>More importantly, this macro should be placed in source files, never in headers. Since the resulting object is has static linkage, if the macro is placed in a header and included by multiple source files, the object will be defined multiple times and will not cause linking errors. Instead, each translation unit will refer to a different object, which could lead to subtle and hard-to-track errors.</p>
<a name="non-recommended-uses"></a>
<h4 >Non-recommended uses</h4>
<p>Note that the macro is not recommended for use with types that are POD or that have C++11 constexpr constructors (trivially constructible and destructible). For those types, it is still recommended to use regular static, whether global or function-local.</p>
<p>This macro will work, but it will add unnecessary overhead.</p>
<a name="reentrancy-thread-safety-deadlocks-and-exception-safety-on-construction"></a>
<h4 >Reentrancy, Thread-safety, Deadlocks, and Exception-safety on Construction</h4>
<p>The Q_GLOBAL_STATIC macro creates an object that initializes itself on first use in a thread-safe manner: if multiple threads attempt to initialize the object at the same time, only one thread will proceed to initialize, while all other threads wait for completion.</p>
<p>If the initialization process throws an exception, the initialization is deemed not complete and will be attempted again when control reaches any use of the object. If there are any threads waiting for initialization, one of them will be woken up to attempt to initialize.</p>
<p>The macro makes no guarantee about reentrancy from the same thread. If the global static object is accessed directly or indirectly from inside the constructor, a deadlock will surely happen.</p>
<p>In addition, if two Q_GLOBAL_STATIC objects are being initialized on two different threads and each one's initialization sequence accesses the other, a deadlock might happen. For that reason, it is recommended to keep global static constructors simple or, failing that, to ensure that there's no cross-dependency of uses of global static during construction.</p>
<a name="destruction"></a>
<h4 >Destruction</h4>
<p>If the object is never used during the lifetime of the program, aside from the <a href="qglobalstatic.html#exists">QGlobalStatic::exists</a>() and <a href="qglobalstatic.html#isDestroyed">QGlobalStatic::isDestroyed</a>() functions, the contents of type <i>Type</i> will not be created and there will not be any exit-time operation.</p>
<p>If the object is created, it will be destroyed at exit-time, similar to the C <code>atexit</code> function. On most systems, in fact, the destructor will also be called if the library or plugin is unloaded from memory before exit.</p>
<p>Since the destruction is meant to happen at program exit, no thread-safety is provided. This includes the case of plugin or library unload. In addition, since destructors are not supposed to throw exceptions, no exception safety is provided either.</p>
<p>However, reentrancy is permitted: during destruction, it is possible to access the global static object and the pointer returned will be the same as it was before destruction began. After the destruction has completed, accessing the global static object is not permitted, except as noted in the <a href="qglobalstatic.html">QGlobalStatic</a> API.</p>
<p>This function was introduced in Qt 5.1.</p>
<p><b>See also </b><a href="qglobalstatic.html#Q_GLOBAL_STATIC_WITH_ARGS">Q_GLOBAL_STATIC_WITH_ARGS</a>() and <a href="qglobalstatic.html">QGlobalStatic</a>.</p>
<!-- @@@Q_GLOBAL_STATIC -->
<!-- $$$Q_GLOBAL_STATIC_WITH_ARGS[overload1]$$$Q_GLOBAL_STATIC_WITH_ARGS -->
<h3 class="fn" id="Q_GLOBAL_STATIC_WITH_ARGS"><a name="Q_GLOBAL_STATIC_WITH_ARGS"></a><span class="name">Q_GLOBAL_STATIC_WITH_ARGS</span>(<i>Type</i>, <i>VariableName</i>, <i>Arguments</i>)</h3>
<p>Creates a global and static object of type <a href="qglobalstatic.html">QGlobalStatic</a>, of name <i>VariableName</i>, initialized by the arguments <i>Arguments</i> and that behaves as a pointer to <i>Type</i>. The object created by Q_GLOBAL_STATIC_WITH_ARGS initializes itself on the first use, which means that it will not increase the application or the library's load time. Additionally, the object is initialized in a thread-safe manner on all platforms.</p>
<p>The typical use of this macro is as follows, in a global context (that is, outside of any function bodies):</p>
<pre class="cpp">
Q_GLOBAL_STATIC_WITH_ARGS(MyType<span class="operator">,</span> staticType<span class="operator">,</span> (<span class="number">42</span><span class="operator">,</span> <span class="string">"Hello"</span><span class="operator">,</span> <span class="string">"World"</span>))
</pre>
<p>The <i>Arguments</i> macro parameter must always include the parentheses or, if C++11 uniform initialization is allowed, the braces.</p>
<p>Aside from the actual initialization of the contents with the supplied arguments, this macro behaves identically to <a href="qglobalstatic.html#Q_GLOBAL_STATIC">Q_GLOBAL_STATIC</a>(). Please see that macro's documentation for more information.</p>
<p>This function was introduced in Qt 5.1.</p>
<p><b>See also </b><a href="qglobalstatic.html#Q_GLOBAL_STATIC">Q_GLOBAL_STATIC</a>() and <a href="qglobalstatic.html">QGlobalStatic</a>.</p>
<!-- @@@Q_GLOBAL_STATIC_WITH_ARGS -->
</div>
</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>
distrib
>
Mageia
>
6
>
armv5tl
>
media
>
core-updates
>
by-pkgid
>
768f7d9f703884aa2562bf0a651086df
>
files
>
407
