Qt
Internal/Contributor docs for the Qt SDK. Note: These are NOT official API docs; those are found at https://doc.qt.io/
Loading...
Searching...
No Matches
qapplicationstatic.qdoc
Go to the documentation of this file.
1// Copyright (C) 2021 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
3
4/*!
5 \headerfile <QApplicationStatic>
6 \inmodule QtCore
7*/
8
9/*!
10 \macro Q_APPLICATION_STATIC(Type, VariableName, ...)
11 \since 6.3
12 \relates <QApplicationStatic>
13
14 This macro extends Q_GLOBAL_STATIC and creates a global and static object
15 of type \l QGlobalStatic, of name \a VariableName, initialized by the
16 variadic arguments, and that behaves as a pointer to \a Type, where the
17 actual lifetime of the type is bound to the QCoreApplication. The object
18 created by Q_APPLICATION_STATIC initializes itself on the first use, which
19 means that it will not increase the application or the library's load time.
20 Additionally, the object is initialized in a thread-safe manner on all
21 platforms.
22
23 In contrast to Q_GLOBAL_STATIC where the type is only meant to be destroyed at
24 program exit, here the actual lifetime of the type is bound to the lifetime of
25 the QCoreApplication. This makes it ideal to store semi-static QObjects, which
26 should also be destroyed once the QCoreApplication is destroyed. This means the
27 type will get deleted once the QCoreApplication emits the destroyed signal.
28 It is permitted for the object to be recreated when it's accessed again, if
29 a new QCoreApplication has also been created.
30
31 Since the value is bound to the QCoreApplication, it should only ever be
32 accessed if there is a valid QCoreApplication::instance(). Accessing this
33 object before QCoreApplication is created or after it's destroyed will
34 produce warnings and may have unpredictable behavior.
35
36 The typical use of this macro is as follows, in a global context (that is,
37 outside of any function bodies):
38
39 \code
40 Q_APPLICATION_STATIC(MyQObjectType, staticType, "some string", function())
41 \endcode
42
43 Do note that the arguments passed in variadic fashion to this macro are
44 evaluated every time the object is constructed, so in the above example,
45 the function \c{function} will be called more than once if the object is
46 recreated.
47
48 Aside from the value also being bound to the lifetime of the QCoreApplication,
49 this macro behaves identically to Q_GLOBAL_STATIC(). Please see that macro's
50 documentation for more information.
51
52 \section1 Threading guarantees
53
54 The Q_APPLICATION_STATIC macro ensures that the object is initialized only
55 once (per lifetime of a QCoreApplication), even if multiple threads try to
56 concurrently access the object. This is done by providing a per-object
57 mutex; application and library developers need to be aware that their
58 object will be constructed with this mutex locked and therefore must not
59 reenter the same object's initialization, or a deadlock will occur.
60
61 There is no thread-safety on the destruction of the object: user code must
62 not access this object once the QCoreApplication destructor starts to run.
63 User code must arrange to ensure this does not happen, such as by not
64 accessing it once the main thread's event loop has exited.
65
66 Like Q_GLOBAL_STATIC, Q_APPLICATION_STATIC provides no thread-safety
67 guarantees for accesses to the object once creation is finished. It is up
68 to user code to ensure that no racy data accesses happen.
69
70 In case the object created by this operation is a QObject, its associated
71 thread will be the one that succeeded in creating it. It will be destroyed
72 by the main thread, so a \l{QObject::}{moveToThread()} to the main thread
73 or to no thread before destruction is adviseable. Doing so from the
74 constructor of the class in question is a sensible solution if one can't
75 guarantee that the main thread will be the one to initialize the object.
76
77 \omit
78 \section1 Implementation details
79 See \l Q_GLOBAL_STATIC implementation details for an introduction.
80
81 Q_APPLICATION_STATIC uses the same \l QGlobalStatic public class that
82 Q_GLOBAL_STATIC does, but instead uses a QtGlobalStatic::ApplicationHolder
83 template class as the template parameter. The differences to
84 QtGlobalStatic::Holder are:
85
86 \list
87 \li The ApplicationHolder class is empty. Unlike Holder, the storage is
88 provided as a \c {static inline} member, simply so that the static
89 member reset() function can access it without having to save the
90 pointer in a lambda.
91
92 \li The ApplicationHolder constructor is trivial; initialization of the
93 type is instead deferred to the \c pointer() function. This means the
94 C++11 thread-safe initialization of statics does not protect the
95 object.
96
97 \li Instead, ApplicationHolder provides a mutex (implemented as a \c
98 {static inline} member of type \l QBasicMutex) and locks it before
99 constructing or destructing the object.
100
101 \li After constructing the object, it will QObject::connect() the
102 QCoreApplication::destroyed() signal to a function that will in turn
103 destroy the object.
104
105 \li The destructor will destroy the object if the application is
106 exiting without first destroying the QCoreApplication object (i.e., a
107 call to \c ::exit) or this Q_APPLICATION_STATIC is part of a plugin
108 that is being unloaded.
109 \endlist
110
111 \endomit
112
113 \sa Q_GLOBAL_STATIC, QGlobalStatic
114*/