En esta página

QGlobalStatic Struct

template <typename Holder> struct QGlobalStatic

La clase QGlobalStatic se utiliza para implementar un objeto estático global. Más información...

Encabezado: #include <QGlobalStatic>
CMake: find_package(Qt6 REQUIRED COMPONENTS Core)
target_link_libraries(mytarget PRIVATE Qt6::Core)
qmake: QT += core

Nota: Todas las funciones de esta estructura son seguras para subprocesos.

Tipos públicos

Funciones públicas

bool exists() const
bool isDestroyed() const
operator QGlobalStatic<Holder>::Type *()
QGlobalStatic<Holder>::Type &operator*()
QGlobalStatic<Holder>::Type *operator->()

Macros

Q_GLOBAL_STATIC(Type, variableName, ...)

Descripción detallada

QGlobalStatic<Holder> es una clase de plantilla en la que Holder es un tipo interno generado por la macro Q_GLOBAL_STATIC(). Se puede acceder al tipo visible para el usuario del objeto estático global a través de la definición de tipo Type.

La clase QGlobalStatic es la API de interfaz que se exporta cuando se utiliza Q_GLOBAL_STATIC(). Consulta la documentación de la macro para obtener más información sobre sus requisitos y cuándo utilizarla.

Normalmente, nunca utilizarás esta clase directamente, sino que utilizarás la macro Q_GLOBAL_STATIC(), de la siguiente manera:

Q_GLOBAL_STATIC(MyType, myGlobal)

El ejemplo anterior crea un objeto de tipo QGlobalStatic denominado myGlobal. Tras la declaración anterior, el objeto myGlobal puede utilizarse como si fuera un puntero a un objeto de tipo MyType, con la garantía de que se inicializará exactamente una vez. Además de su uso como puntero, el objeto ofrece dos métodos para determinar el estado actual de la variable global: exists() y isDestroyed().

Véase también Q_GLOBAL_STATIC().

Documentación sobre tipos de miembros

[alias] QGlobalStatic::Type

Este tipo es equivalente al parámetro « Type » que se pasa a las macros « Q_GLOBAL_STATIC()» o «Q_GLOBAL_STATIC_WITH_ARGS()». Se utiliza en los tipos de retorno de algunas funciones.

Documentación de funciones miembro

[noexcept] bool QGlobalStatic::exists() const

Esta función devuelve « true » si el objeto estático global ya ha completado su inicialización (es decir, si el constructor del tipo ya ha devuelto un valor) y aún no ha completado su destrucción. En particular, hay que tener en cuenta que esta función devuelve « false » si la inicialización aún está en curso.

Una vez que esta función haya devuelto «true» una vez, nunca volverá a devolver «false» hasta que se destruya el objeto estático global. Esto último ocurre al salir del programa o cuando se descarga el complemento o la biblioteca que contiene el objeto estático global.

Esta función se puede llamar de forma segura en cualquier momento de la ejecución del programa: no puede fallar ni provocar un interbloqueo. Además, no provocará la creación de los contenidos si aún no se han creado.

Esta función resulta útil si se pueden determinar las condiciones iniciales del objeto estático global y se prefiere evitar una operación de construcción que podría resultar costosa.

Por ejemplo, en el siguiente ejemplo de código, esta función se utiliza para evitar la creación del objeto estático global denominado « globalState » y devuelve un valor por defecto:

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

Aviso sobre seguridad entre subprocesos: esta función es segura entre subprocesos en el sentido de que puede invocarse desde cualquier subproceso en cualquier momento y siempre devolverá una respuesta válida. Sin embargo, debido a la naturaleza no atómica de la construcción, esta función puede devolver «false» durante un breve periodo de tiempo tras completarse la construcción.

Aviso sobre el orden de la memoria: esta función no garantiza ningún orden de la memoria. De ello se encargan las funciones de acceso que devuelven el puntero o la referencia al contenido. Si se omiten las funciones de acceso e intenta acceder a algún estado global establecido por el constructor, asegúrese de utilizar la semántica de orden de memoria correcta que proporcionan QAtomicInt o QAtomicPointer.

Véase también isDestroyed().

[noexcept] bool QGlobalStatic::isDestroyed() const

Esta función devuelve « true » si el objeto estático global ya ha completado su destrucción (es decir, si el destructor del tipo ya ha devuelto un valor). En particular, hay que tener en cuenta que esta función devuelve « false » si la destrucción aún está en curso.

Una vez que esta función haya devuelto «true» una vez, nunca volverá a devolver «false» hasta que se reinicie el programa o se descargue y vuelva a cargar el complemento o la biblioteca que contiene el objeto estático global.

Esta función se puede invocar de forma segura en cualquier momento de la ejecución del programa: no puede fallar ni provocar un interbloqueo. Además, no provocará que se cree el contenido si aún no se ha creado.

Esta función resulta útil en código que pueda ejecutarse al cerrar el programa, para determinar si aún se puede acceder a los contenidos o no.

Véase también exists().

QGlobalStatic::operator QGlobalStatic<Holder>::Type *()

Esta función devuelve la dirección del contenido de esta variable estática global. Si el contenido aún no se ha creado, esta función lo creará de forma segura para los hilos. Si el contenido ya se ha destruido, esta función devolverá un puntero nulo.

Esta función se puede utilizar, por ejemplo, para almacenar el puntero al contenido de la variable global estática en una variable local, evitando así múltiples llamadas a la función. La implementación de Q_GLOBAL_STATIC() ya es bastante eficiente, pero en secciones en las que el rendimiento es crítico podría resultar útil echar una mano al compilador. Por ejemplo:

Q_GLOBAL_STATIC(MyType, globalState)
QString someState()
{
    if (globalState::isDestroyed())
        return QString();
    MyType *state = globalState;
    if (state->condition)
        return state->value;
    else
        return state->worth;
}

Véanse también operator->() y operator*().

QGlobalStatic<Holder>::Type &QGlobalStatic::operator*()

Esta función devuelve una referencia al contenido de esta variable estática global. Si el contenido aún no se ha creado, esta función lo creará de forma segura para los hilos.

Esta función no comprueba si el contenido ya ha sido destruido. Si se llama a esta función después de que el objeto haya sido destruido, devolverá una referencia no válida que no debe utilizarse.

Véase también exists() y isDestroyed().

QGlobalStatic<Holder>::Type *QGlobalStatic::operator->()

Esta función devuelve la dirección del contenido de esta variable estática global. Si el contenido aún no se ha creado, esta función lo creará de forma segura para los subprocesos.

Esta función no comprueba si el contenido ya ha sido destruido y nunca devolverá `null`. Si se invoca esta función después de que el objeto haya sido destruido, devolverá un puntero colgante que no debe desreferenciarse.

Véase también exists() y isDestroyed().

Documentación de macros

Q_GLOBAL_STATIC(Type, variableName, ...)

Crea un objeto global y estático de tipo ` QGlobalStatic`, denominado ` variableName`. Se comporta como un puntero a ` Type`. El objeto creado por `Q_GLOBAL_STATIC` se inicializa por sí mismo la primera vez que se utiliza, lo que significa que no aumentará el tiempo de carga de la aplicación ni de la biblioteca. Además, el objeto se inicializa de forma segura para subprocesos en todas las plataformas.

Desde Qt 6.3, esta macro admite argumentos variádicos, que se utilizan para inicializar el objeto, lo que hace innecesario el uso de ` Q_GLOBAL_STATIC_WITH_ARGS `. Ten en cuenta que los argumentos no requieren un par de paréntesis adicional, a diferencia de la macro anterior.

El uso habitual de esta macro es el siguiente, en un contexto global (es decir, fuera del cuerpo de cualquier función o clase):

Q_GLOBAL_STATIC(MyType, myGlobal)

Esta macro está pensada para sustituir a los objetos estáticos globales que no son POD (Plain Old Data, o en términos de C++11, que no están formados por un tipo trivial), de ahí su nombre. Por ejemplo, el siguiente código C++ crea un objeto estático global:

static MyType myGlobal;

En comparación con Q_GLOBAL_STATIC, y suponiendo que MyType sea una clase o estructura que tenga un constructor, un destructor o que, por cualquier otro motivo, no sea POD, esta última presenta los siguientes inconvenientes:

  • requiere la inicialización en tiempo de carga de ` myGlobal ` (es decir, se llama al constructor por defecto de ` MyType ` cuando se carga la biblioteca o la aplicación);
  • el objeto se inicializará aunque nunca se utilice;
  • el orden de inicialización y destrucción entre las diferentes unidades de traducción no está determinado, lo que da lugar a posibles usos, antes de la inicialización o después de la destrucción, por parte de los constructores o destructores de otras variables globales.

La macro Q_GLOBAL_STATIC resuelve todos estos problemas al garantizar una inicialización segura para subprocesos en el primer uso y al permitir al usuario consultar si el tipo ya ha sido destruido, con el fin de evitar el problema de uso tras la destrucción (véase QGlobalStatic::isDestroyed()).

Constructor y destructor

En el caso de Q_GLOBAL_STATIC, cuando solo se le proporcionan un tipo y un nombre de variable, su Type debe poder construirse de forma predeterminada y destruirse públicamente. De lo contrario, Type debe tener un constructor público que acepte los argumentos restantes de la macro. En el caso de Q_GLOBAL_STATIC_WITH_ARGS(), debe existir un constructor público que acepte el tercer argumento de la macro como su lista de parámetros.

No es posible utilizar Q_GLOBAL_STATIC con un ` Type ` cuyo constructor o destructor correspondiente sea `protected` o `private`. Si el tipo en cuestión declara esos miembros como «protected», es posible solucionar el problema derivando de dicho tipo y creando un constructor y un destructor públicos. Si el tipo los declara como «private», es necesaria una declaración «friend» antes de derivar.

Por ejemplo, lo siguiente basta para crear un ` MyType ` basado en un ` MyOtherType ` previamente definido que tenga un constructor por defecto protegido y/o un destructor protegido (o que los declare privados, pero que también declare ` MyType ` como amigo).

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

No se requiere ningún cuerpo para ` MyType `, ya que el destructor es un miembro implícito, al igual que el constructor por defecto si no se definen otros constructores. Sin embargo, para su uso con argumentos tras ` Type ` y ` variableName`, o con `Q_GLOBAL_STATIC_WITH_ARGS()`, es necesario un cuerpo de constructor adecuado:

class MyType : public MyOtherType
{
public:
    MyType(int i) : MyOtherType(i) {}
};
Q_GLOBAL_STATIC(MyType, myGlobal, 42)

Como alternativa (dado que C++11 introdujo los constructores heredados), se podría escribir:

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

Ubicación

La macro Q_GLOBAL_STATIC crea un tipo y una variable de ese tipo que es necesariamente estática, en el ámbito global. No es posible colocar la macro Q_GLOBAL_STATIC dentro de una función o del cuerpo de una clase (hacerlo provocará errores de compilación).

Y lo que es más importante, esta macro debe colocarse en archivos fuente, nunca en encabezados. Dado que el objeto resultante tiene enlace estático, si la macro se coloca en un archivo de cabecera y es incluida por varios archivos fuente, el objeto se definirá varias veces y no provocará errores de enlace. En su lugar, cada unidad de traducción hará referencia a un objeto diferente, lo que podría dar lugar a errores sutiles y difíciles de detectar.

Ten en cuenta que no se recomienda utilizar la macro con tipos que sean POD o que tengan constructores constexpr de C++11 (trivialmente construibles y destructibles). Para esos tipos, sigue recomendándose utilizar la palabra «static» normal, ya sea global o local a la función.

Esta macro funcionará, pero añadirá una sobrecarga innecesaria.

Reentrancia, seguridad entre subprocesos, interbloqueos y seguridad ante excepciones en la construcción

La macro Q_GLOBAL_STATIC crea un objeto que se inicializa por sí mismo en su primer uso de forma segura para subprocesos: si varios subprocesos intentan inicializar el objeto al mismo tiempo, solo un subproceso procederá a la inicialización, mientras que el resto esperará a que esta finalice.

Si el proceso de inicialización lanza una excepción, la inicialización se considera incompleta y se volverá a intentar cuando el control llegue a cualquier uso del objeto. Si hay hilos esperando la inicialización, se activará uno de ellos para intentar la inicialización.

La macro no garantiza la reentrancia desde el mismo hilo. Si se accede al objeto estático global, directa o indirectamente, desde el interior de su propio constructor, se producirá sin duda un interbloqueo.

Además, si se están inicializando dos objetos Q_GLOBAL_STATIC en dos subprocesos diferentes y la secuencia de inicialización de cada uno accede al otro, podría producirse un interbloqueo. Por ese motivo, se recomienda que los constructores de objetos estáticos globales sean sencillos o, en su defecto, asegurarse de que no haya dependencias cruzadas en el uso de los objetos estáticos globales durante la construcción.

Destrucción

Si el objeto nunca se utiliza durante el tiempo de vida del programa, salvo en las funciones ` QGlobalStatic::exists()` y ` QGlobalStatic::isDestroyed()`, no se creará el contenido de tipo ` Type ` y no habrá ninguna operación en el momento de la salida.

Si se crea el objeto, se destruirá al salir del programa, de forma similar a la función ` atexit() ` de C. De hecho, en la mayoría de los sistemas, el destructor también se llamará si la biblioteca o el complemento se descargan de la memoria antes de salir del programa.

Dado que la destrucción está pensada para producirse al salir del programa, no se garantiza la seguridad entre subprocesos. Esto incluye el caso de la descarga del complemento o de la biblioteca. Además, dado que no se espera que los destructores lancen excepciones, tampoco se garantiza la seguridad frente a excepciones.

Sin embargo, se permite la reentrada: durante la destrucción, es posible acceder al objeto estático global y el puntero devuelto será el mismo que antes de que comenzara la destrucción. Una vez completada la destrucción, no se permite acceder al objeto estático global, salvo en los casos indicados en la API de ` QGlobalStatic `.

Véase también Q_APPLICATION_STATIC() y QGlobalStatic.

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.