<QApplicationStatic>

Macro Documentation

[since 6.3] Q_APPLICATION_STATIC(Type, VariableName, ...)

This macro extends Q_GLOBAL_STATIC and creates a global and static object of type QGlobalStatic, of name VariableName, initialized by the variadic arguments, and that behaves as a pointer to Type, where the actual lifetime of the type is bound to the QCoreApplication. The object created by Q_APPLICATION_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.

In contrast to Q_GLOBAL_STATIC where the type is only meant to be destroyed at program exit, here the actual lifetime of the type is bound to the lifetime of 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. 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 object before QCoreApplication is created or after it's destroyed will produce warnings and may have unpredictable behavior.

The typical use of this macro is as follows, in a global context (that is, outside of any function bodies):

Q_APPLICATION_STATIC(MyQObjectType, staticType, "some string", function())

Do note that the arguments passed in variadic fashion to this macro are evaluated every time the object is constructed, so in the above example, the function function will be called more than once if the object is recreated.

Aside from the value also being bound to the lifetime of the QCoreApplication, this macro behaves identically to Q_GLOBAL_STATIC(). Please see that macro's documentation for more information.

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 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.

This macro was introduced in Qt 6.3.

See also Q_GLOBAL_STATIC and QGlobalStatic.