diff options
Diffstat (limited to 'src/corelib/kernel/qapplicationstatic.qdoc')
| -rw-r--r-- | src/corelib/kernel/qapplicationstatic.qdoc | 58 |
1 files changed, 29 insertions, 29 deletions
diff --git a/src/corelib/kernel/qapplicationstatic.qdoc b/src/corelib/kernel/qapplicationstatic.qdoc index 76507a2824..5cbac65df9 100644 --- a/src/corelib/kernel/qapplicationstatic.qdoc +++ b/src/corelib/kernel/qapplicationstatic.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2021 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \macro Q_APPLICATION_STATIC(Type, VariableName, ...) @@ -44,9 +20,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 @@ -69,6 +44,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. |