Detailed Description

See also Q_GLOBAL_STATIC(), Q_GLOBAL_STATIC_WITH_ARGS()

This type is equivalent to the Type parameter passed to the Q_GLOBAL_STATIC() or Q_GLOBAL_STATIC_WITH_ARGS() macros. It is used in the return types of some functions.

This function returns true if the global static object has already completed initialization (that is, if the constructor for the type has already returned). In specific, note that this function returns false if the initialization is still in progress.

Once this function has returned true once, it will never return false again until either the program is restarted or the plugin or library containing the global static is unloaded and reloaded.

This function is safe to call at any point in the program execution: it cannot fail and cannot cause a deadlock. Additionally, it will not cause the contents to be created if they have not yet been created.

This function is useful if one can determine the initial conditions of the global static object and would prefer to avoid a possibly expensive construction operation.

For example, in the following code sample, this function is used to short-circuit the creation of the global static called globalState and returns a default value:

Q_GLOBAL_STATIC(MyType, globalState)
QString someState()
{
    if (globalState.exists())
        return globalState->someState;
    return QString();
}

Thread-safety notice: this function is thread-safe in the sense that it may be called from any thread at any time and will always return a valid reply. But due to the non-atomic nature of construction, this function may return false for a short time after the construction has completed.

Memory ordering notice: this function does not impose any memory ordering guarantees. That is instead provided by the accessor functions that return the pointer or reference to the contents. If you bypass the accessor functions and attempt to access some global state set by the constructor, be sure to use the correct memory ordering semantics provided by QAtomicInt or QAtomicPointer.

See Also▲

This function returns true if the global static object has already completed destruction (that is, if the destructor for the type has already returned). In specific, note that this function returns false if the destruction is still in progress.

Once this function has returned true once, it will never return false again until either the program is restarted or the plugin or library containing the global static is unloaded and reloaded.

This function is safe to call at any point in the program execution: it cannot fail and cannot cause a deadlock. Additionally, it will not cause the contents to be created if they have not yet been created.

This function is useful in code that may be executed at program shutdown, to determine whether the contents may still be accessed or not.

See Also▲

This function returns the address of the contents of this global static. If the contents have not yet been created, they will be created thread-safely by this function. If the contents have already been destroyed, this function will return a null pointer.

This function can be used, for example, to store the pointer to the contents of the global static in a local variable, thus avoiding multiple calls to the function. The implementation of Q_GLOBAL_STATIC() is quite efficient already, but in performance-critical sections it might be useful to help the compiler a little. For example:

Q_GLOBAL_STATIC(MyType, globalState)
QString someState()
{
    MyType *state = globalState;
    if (!state) {
        // we're in a post-destruction state
        return QString();
    }
    if (state->condition)
        return state->value1;
    else
        return state->value2;
}

See Also▲

This function returns a reference to the contents of this global static. If the contents have not yet been created, they will be created thread-safely by this function.

This function does not check if the contents have already been destroyed. If this function is called after the object has been destroyed, it will return an invalid reference that must not be used.

This function returns the address of the contents of this global static. If the contents have not yet been created, they will be created thread-safely by this function.

This function does not check if the contents have already been destroyed and will never return null. If this function is called after the object has been destroyed, it will return a dangling pointer that should not be dereferenced.

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

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.

This macro was introduced in Qt 6.3.

See Also▲

Creates a global and static object of type QGlobalStatic, of name VariableName and that behaves as a pointer to Type. The object created by Q_GLOBAL_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.

Since Qt 6.3, this macro admits variadic arguments, which are used to initialize the object, thus making the need for Q_GLOBAL_STATIC_WITH_ARGS unnecessary. Please note the arguments do not require an extra set of parentheses, unlike the older macro.

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

Q_GLOBAL_STATIC(MyType, staticType)

This macro is intended to replace global static objects that are not POD (Plain Old Data, or in C++11 terms, not made of a trivial type), hence the name. For example, the following C++ code creates a global static:

static MyType staticType;

Compared to Q_GLOBAL_STATIC, and assuming that MyType is a class or struct that has a constructor, a destructor, or is otherwise non-POD, the above has the following drawbacks:

• it requires load-time initialization of MyType (that is, the default constructor for MyType is called when the library or application is loaded);

• the type will be initialized even if it is never used;

• the order of initialization and destruction among different translation units is not determined, leading to possible uses before initialization or after destruction;

The Q_GLOBAL_STATIC macro solves all of the above problems by guaranteeing thread-safe initialization on first use and allowing the user to query for whether the type has already been destroyed, to avoid the use-after-destruction problem (see QGlobalStatic::isDestroyed()).

Constructor and Destructor▲

class MyType : public MyOtherType { };
Q_GLOBAL_STATIC(MyType, staticType)

class MyType : public MyOtherType
{
public:
    MyType(int i) : MyOtherType(i) {}
};
Q_GLOBAL_STATIC_WITH_ARGS(MyType, staticType, (42))

class MyType : public MyOtherType
{
public:
    using MyOtherType::MyOtherType;
};
Q_GLOBAL_STATIC_WITH_ARGS(MyType, staticType, (42))

Placement▲

Non-recommended uses▲

Reentrancy, Thread-safety, Deadlocks, and Exception-safety on Construction▲

Destruction▲

Notes▲

See Also▲

QGlobalStatic::Type *QGlobalStatic::operator()()▲

[since 5.1] Q_GLOBAL_STATIC_WITH_ARGS(Type, VariableName, Arguments)▲

Q_GLOBAL_STATIC_WITH_ARGS(MyType, staticType, (42, "Hello", "World"))

Q_GLOBAL_STATIC(MyType, staticType, 42, "Hello", "World")