diff options
Diffstat (limited to 'src/corelib/kernel/qapplicationstatic.qdoc')
| -rw-r--r-- | src/corelib/kernel/qapplicationstatic.qdoc | 37 |
1 files changed, 33 insertions, 4 deletions
diff --git a/src/corelib/kernel/qapplicationstatic.qdoc b/src/corelib/kernel/qapplicationstatic.qdoc index 82eb7265ff..1d13fbd84a 100644 --- a/src/corelib/kernel/qapplicationstatic.qdoc +++ b/src/corelib/kernel/qapplicationstatic.qdoc @@ -2,9 +2,14 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! + \headerfile <QApplicationStatic> + \inmodule QtCore +*/ + +/*! \macro Q_APPLICATION_STATIC(Type, VariableName, ...) \since 6.3 - \relates QGlobalStatic + \relates <QApplicationStatic> This macro extends Q_GLOBAL_STATIC and creates a global and static object of type \l QGlobalStatic, of name \a VariableName, initialized by the @@ -20,9 +25,8 @@ the QCoreApplication. This makes it ideal to store semi-static QObjects, which should also be destroyed once the QCoreApplication is destroyed. This means the type will get deleted once the QCoreApplication emits the destroyed signal. - However, as long as the actual holder is still in the initialized state, the - type will be recreated when it's accessed again once a new QCoreApplication - has been created. + It is permitted for the object to be recreated when it's accessed again, if + a new QCoreApplication has also been created. Since the value is bound to the QCoreApplication, it should only ever be accessed if there is a valid QCoreApplication::instance(). Accessing this @@ -45,6 +49,31 @@ this macro behaves identically to Q_GLOBAL_STATIC(). Please see that macro's documentation for more information. + \section1 Threading guarantees + + The Q_APPLICATION_STATIC macro ensures that the object is initialized only + once (per lifetime of a QCoreApplication), even if multiple threads try to + concurrently access the object. This is done by providing a per-object + mutex; application and library developers need to be aware that their + object will be constructed with this mutex locked and therefore must not + reenter the same object's initialization, or a deadlock will occur. + + There is no thread-safety on the destruction of the object: user code must + not access this object once the QCoreApplication destructor starts to run. + User code must arrange to ensure this does not happen, such as by not + accessing it once the main thread's event loop has exited. + + Like Q_GLOBAL_STATIC, Q_APPLICATION_STATIC provides no thread-safety + guarantees for accesses to the object once creation is finished. It is up + to user code to ensure that no racy data accesses happen. + + In case the object created by this operation is a QObject, its associated + thread will be the one that succeeded in creating it. It will be destroyed + by the main thread, so a \l{QObject::}{moveToThread()} to the main thread + or to no thread before destruction is adviseable. Doing so from the + constructor of the class in question is a sensible solution if one can't + guarantee that the main thread will be the one to initialize the object. + \omit \section1 Implementation details See \l Q_GLOBAL_STATIC implementation details for an introduction. |