From 4ff074a67e8f3193a789eb437a6549b181b8dc95 Mon Sep 17 00:00:00 2001 From: Thiago Macieira Date: Wed, 5 Apr 2023 12:23:10 -0300 Subject: [PATCH] QApplicationStatic: document the thread-safety guarantees Change-Id: Idd5e1bb52be047d7b4fffffd17531331df25c18c Reviewed-by: Marc Mutz --- src/corelib/kernel/qapplicationstatic.qdoc | 30 +++++++++++++++++++--- 1 file changed, 27 insertions(+), 3 deletions(-) diff --git a/src/corelib/kernel/qapplicationstatic.qdoc b/src/corelib/kernel/qapplicationstatic.qdoc index 82eb7265ff..5cbac65df9 100644 --- a/src/corelib/kernel/qapplicationstatic.qdoc +++ b/src/corelib/kernel/qapplicationstatic.qdoc @@ -20,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 @@ -45,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.