/****************************************************************************
**
** 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$
**
****************************************************************************/

/*!
    \macro Q_APPLICATION_STATIC(Type, VariableName, ...)
    \since 6.3
    \relates QGlobalStatic

    This macro extends Q_GLOBAL_STATIC and creates a global and static object
    of type \l QGlobalStatic, of name \a VariableName, initialized by the
    variadic arguments, and that behaves as a pointer to \a 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.
    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.

    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):

    \code
        Q_APPLICATION_STATIC(MyQObjectType, staticType, "some string", function())
    \endcode

    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 \c{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.

    \omit
    \section1 Implementation details
    See \l Q_GLOBAL_STATIC implementation details for an introduction.

    Q_APPLICATION_STATIC uses the same \l QGlobalStatic public class that
    Q_GLOBAL_STATIC does, but instead uses a QtGlobalStatic::ApplicationHolder
    template class as the template parameter. The differences to
    QtGlobalStatic::Holder are:

    \list
        \li The ApplicationHolder class is empty. Unlike Holder, the storage is
        provided as a \c {static inline} member, simply so that the static
        member reset() function can access it without having to save the
        pointer in a lambda.

        \li The ApplicationHolder constructor is trivial; initialization of the
        type is instead deferred to the \c pointer() function. This means the
        C++11 thread-safe initialization of statics does not protect the
        object.

        \li Instead, ApplicationHolder provides a mutex (implemented as a \c
        {static inline} member of type \l QBasicMutex) and locks it before
        constructing or destructing the object.

        \li After constructing the object, it will QObject::connect() the
        QCoreApplication::destroyed() signal to a function that will in turn
        destroy the object.

        \li The destructor will destroy the object if the application is
        exiting without first destroying the QCoreApplication object (i.e., a
        call to \c ::exit) or this Q_APPLICATION_STATIC is part of a plugin
        that is being unloaded.
    \endlist

    \endomit

    \sa Q_GLOBAL_STATIC, QGlobalStatic
*/