Back to Qt.io
Contact Us Blog Download Qt
En esta página

QAtomicPointer Class

template <typename T> class QAtomicPointer

La clase QAtomicPointer es una clase plantilla que proporciona operaciones atómicas independientes de la plataforma sobre punteros. Más...

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

Funciones Públicas

QAtomicPointer(T *value = nullptr)
QAtomicPointer(const QAtomicPointer<T> &other)
T *fetchAndAddAcquire(qptrdiff valueToAdd)
T *fetchAndAddOrdered(qptrdiff valueToAdd)
T *fetchAndAddRelaxed(qptrdiff valueToAdd)
T *fetchAndAddRelease(qptrdiff valueToAdd)
T *fetchAndStoreAcquire(T *newValue)
T *fetchAndStoreOrdered(T *newValue)
T *fetchAndStoreRelaxed(T *newValue)
T *fetchAndStoreRelease(T *newValue)
T *loadAcquire() const
T *loadRelaxed() const
void storeRelaxed(T *newValue)
void storeRelease(T *newValue)
bool testAndSetAcquire(T *expectedValue, T *newValue)
bool testAndSetAcquire(T *expectedValue, T *newValue, T *&currentValue)
bool testAndSetOrdered(T *expectedValue, T *newValue)
bool testAndSetOrdered(T *expectedValue, T *newValue, T *&currentValue)
bool testAndSetRelaxed(T *expectedValue, T *newValue)
bool testAndSetRelaxed(T *expectedValue, T *newValue, T *&currentValue)
bool testAndSetRelease(T *expectedValue, T *newValue)
bool testAndSetRelease(T *expectedValue, T *newValue, T *&currentValue)
QAtomicPointer<T> &operator=(const QAtomicPointer<T> &other)

Miembros Públicos Estáticos

bool isFetchAndAddNative()
bool isFetchAndAddWaitFree()
bool isFetchAndStoreNative()
bool isFetchAndStoreWaitFree()
bool isTestAndSetNative()
bool isTestAndSetWaitFree()

Macros

Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_ALWAYS_NATIVE
Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_NOT_NATIVE
Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_SOMETIMES_NATIVE
Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_WAIT_FREE
Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_ALWAYS_NATIVE
Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_NOT_NATIVE
Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_SOMETIMES_NATIVE
Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_WAIT_FREE
Q_ATOMIC_POINTER_TEST_AND_SET_IS_ALWAYS_NATIVE
Q_ATOMIC_POINTER_TEST_AND_SET_IS_NOT_NATIVE
Q_ATOMIC_POINTER_TEST_AND_SET_IS_SOMETIMES_NATIVE
Q_ATOMIC_POINTER_TEST_AND_SET_IS_WAIT_FREE

Descripción Detallada

Para operaciones atómicas sobre enteros, véase la clase QAtomicInteger.

Una operación atómica es una operación compleja que se completa sin interrupción. La clase QAtomicPointer proporciona test-and-set, fetch-and-store, y fetch-and-add atómicos para punteros.

La API Atómica

Ordenación de la memoria

QAtomicPointer proporciona varias implementaciones de las funciones atomic test-and-set, fetch-and-store y fetch-and-add. Cada implementación define una semántica de ordenación de memoria que describe cómo el procesador ejecuta los accesos a memoria que rodean a la instrucción atómica. Dado que muchas arquitecturas modernas permiten la ejecución fuera de orden y el ordenamiento de memoria, es necesario utilizar la semántica correcta para garantizar que su aplicación funcione correctamente en todos los procesadores.

  • Relajado - el orden de memoria no está especificado, dejando que el compilador y el procesador reordenen libremente los accesos a memoria.
  • Acquire - el acceso a memoria que sigue a la operación atómica (en el orden del programa) no puede ser reordenado antes de la operación atómica.
  • Release - el acceso a la memoria antes de la operación atómica (en el orden del programa) no puede ser reordenado después de la operación atómica.
  • Ordered - la misma semántica de Acquire y Release combinada.

Test-and-set

Si el valor actual del QAtomicPointer es un valor esperado, las funciones test-and-set asignan un nuevo valor al QAtomicPointer y devuelven true. Si los valores no coinciden, estas funciones no hacen nada y devuelven false. Esta operación equivale al siguiente código:

if (currentValue == expectedValue) {
    currentValue = newValue;
    return true;
}
return false;

Existen 4 funciones test-and-set: testAndSetRelaxed(), testAndSetAcquire(), testAndSetRelease(), y testAndSetOrdered(). Véase más arriba la explicación de las diferentes semánticas de ordenación de la memoria.

Búsqueda y almacenamiento

Las funciones atómicas fetch-and-store leen el valor actual del QAtomicPointer y luego asignan un nuevo valor, devolviendo el valor original. Esta operación equivale al siguiente código:

T *originalValue = currentValue;
currentValue = newValue;
return originalValue;

Existen 4 funciones fetch-and-store: fetchAndStoreRelaxed(), fetchAndStoreAcquire(), fetchAndStoreRelease(), y fetchAndStoreOrdered(). Véase más arriba la explicación de las diferentes semánticas de ordenación de memoria.

Obtención y adición

Las funciones atómicas fetch-and-add leen el valor actual del QAtomicPointer y luego añaden el valor dado al valor actual, devolviendo el valor original. Esta operación equivale al siguiente código:

T *originalValue = currentValue;
currentValue += valueToAdd;
return originalValue;

Hay 4 funciones fetch-and-add: fetchAndAddRelaxed(), fetchAndAddAcquire(), fetchAndAddRelease(), y fetchAndAddOrdered(). Véase más arriba la explicación de las diferentes semánticas de ordenación de la memoria.

Pruebas de funcionamiento de la API atómica

Proporcionar una API atómica independiente de la plataforma que funcione en todos los procesadores es un reto. La API proporcionada por QAtomicPointer garantiza el funcionamiento atómico en todos los procesadores. Sin embargo, dado que no todos los procesadores implementan soporte para cada operación proporcionada por QAtomicPointer, es necesario exponer información sobre el procesador.

Puedes comprobar en tiempo de compilación qué funciones están soportadas en tu hardware utilizando varias macros. Estas te dirán si tu hardware siempre, a veces, o no soporta una operación en particular. Las macros tienen la forma Q_ATOMIC_POINTER_OPERATION_IS_HOW_NATIVE. OPERATION es una de TEST_AND_SET, FETCH_AND_STORE, o FETCH_AND_ADD, y HOW es una de SIEMPRE, A VECES, o NO. Siempre habrá exactamente una macro definida por operación. Por ejemplo, si se define Q_ATOMIC_POINTER_TEST_AND_SET_IS_ALWAYS_NATIVE, no se definirán ni Q_ATOMIC_POINTER_TEST_AND_SET_IS_SOMETIMES_NATIVE ni Q_ATOMIC_POINTER_TEST_AND_SET_IS_NOT_NATIVE.

Una operación que se completa en tiempo constante se dice que no requiere espera. Tales operaciones no se implementan utilizando bloqueos o bucles de ningún tipo. Para las operaciones atómicas que siempre están soportadas, y que son libres de espera, Qt define la Q_ATOMIC_POINTER_OPERATION_IS_WAIT_FREE además de la Q_ATOMIC_POINTER_OPERATION_IS_ALWAYS_NATIVE.

En los casos en los que una operación atómica sólo está soportada en las nuevas generaciones del procesador, QAtomicPointer también proporciona una forma de comprobar en tiempo de ejecución lo que soporta tu hardware con las funciones isTestAndSetNative(), isFetchAndStoreNative(), y isFetchAndAddNative(). Las implementaciones sin espera pueden detectarse mediante las funciones isTestAndSetWaitFree(), isFetchAndStoreWaitFree(), y isFetchAndAddWaitFree().

A continuación se muestra una lista completa de todas las macros de funciones para QAtomicPointer:

Véase también QAtomicInteger y qYieldCpu().

Documentación de funciones miembro

[constexpr noexcept] QAtomicPointer::QAtomicPointer(T *value = nullptr)

Construye un QAtomicPointer con la dirección value.

[noexcept] QAtomicPointer::QAtomicPointer(const QAtomicPointer<T> &other)

Construye una copia de other.

T *QAtomicPointer::fetchAndAddAcquire(qptrdiff valueToAdd)

Obtención y adición atómicas.

Lee el valor actual de este QAtomicPointer y luego añade valueToAdd al valor actual, devolviendo el valor original.

Esta función utiliza la semántica acquire memory ordering, que garantiza que el acceso a la memoria que sigue a la operación atómica (en el orden del programa) no puede reordenarse antes de la operación atómica.

T *QAtomicPointer::fetchAndAddOrdered(qptrdiff valueToAdd)

Obtención y adición atómicas.

Lee el valor actual de este QAtomicPointer y luego añade valueToAdd al valor actual, devolviendo el valor original.

Esta función utiliza la semántica ordenada de memory ordering, que garantiza que el acceso a la memoria antes y después de la operación atómica (en el orden del programa) no puede reordenarse.

T *QAtomicPointer::fetchAndAddRelaxed(qptrdiff valueToAdd)

Obtención y adición atómicas.

Lee el valor actual de este QAtomicPointer y luego añade valueToAdd al valor actual, devolviendo el valor original.

Esta función utiliza una semántica relajada de memory ordering, lo que permite al compilador y al procesador reordenar libremente los accesos a la memoria.

T *QAtomicPointer::fetchAndAddRelease(qptrdiff valueToAdd)

Obtención y adición atómicas.

Lee el valor actual de este QAtomicPointer y luego añade valueToAdd al valor actual, devolviendo el valor original.

Esta función utiliza la semántica release memory ordering, que garantiza que el acceso a la memoria antes de la operación atómica (en el orden del programa) no puede reordenarse después de la operación atómica.

T *QAtomicPointer::fetchAndStoreAcquire(T *newValue)

Búsqueda y almacenamiento atómicos.

Lee el valor actual de este QAtomicPointer y luego le asigna el newValue, devolviendo el valor original.

Esta función utiliza la semántica acquire memory ordering, que garantiza que el acceso a la memoria que sigue a la operación atómica (en el orden del programa) no puede reordenarse antes de la operación atómica.

T *QAtomicPointer::fetchAndStoreOrdered(T *newValue)

Búsqueda y almacenamiento atómicos.

Lee el valor actual de este QAtomicPointer y luego le asigna el newValue, devolviendo el valor original.

Esta función utiliza la semántica memory ordering ordenada, que garantiza que el acceso a la memoria antes y después de la operación atómica (en el orden del programa) no puede reordenarse.

T *QAtomicPointer::fetchAndStoreRelaxed(T *newValue)

Búsqueda y almacenamiento atómicos.

Lee el valor actual de este QAtomicPointer y luego le asigna el newValue, devolviendo el valor original.

Esta función utiliza una semántica relajada de memory ordering, lo que permite al compilador y al procesador reordenar libremente los accesos a la memoria.

T *QAtomicPointer::fetchAndStoreRelease(T *newValue)

Búsqueda y almacenamiento atómicos.

Lee el valor actual de este QAtomicPointer y luego le asigna el newValue, devolviendo el valor original.

Esta función utiliza la semántica release memory ordering, que garantiza que el acceso a la memoria antes de la operación atómica (en el orden del programa) no puede reordenarse después de la operación atómica.

[static constexpr] bool QAtomicPointer::isFetchAndAddNative()

Devuelve true si fetch-and-add se implementa utilizando instrucciones atómicas del procesador, false en caso contrario.

[static constexpr] bool QAtomicPointer::isFetchAndAddWaitFree()

Devuelve true si la función atomic fetch-and-add es wait-free, false en caso contrario.

[static constexpr] bool QAtomicPointer::isFetchAndStoreNative()

Devuelve true si fetch-and-store se implementa utilizando instrucciones atómicas del procesador, false en caso contrario.

[static constexpr] bool QAtomicPointer::isFetchAndStoreWaitFree()

Devuelve true si la función atomic fetch-and-store es wait-free, false en caso contrario.

[static constexpr] bool QAtomicPointer::isTestAndSetNative()

Devuelve true si test-and-set se implementa utilizando instrucciones atómicas del procesador, false en caso contrario.

[static constexpr] bool QAtomicPointer::isTestAndSetWaitFree()

Devuelve true si atomic test-and-set es wait-free, false en caso contrario.

T *QAtomicPointer::loadAcquire() const

Carga atómicamente el valor de este QAtomicPointer utilizando la ordenación de memoria "Adquirir". El valor no se modifica de ninguna manera, pero ten en cuenta que no hay garantía de que permanezca así.

Véase también storeRelease() y loadRelaxed().

T *QAtomicPointer::loadRelaxed() const

Carga atómicamente el valor de este QAtomicPointer utilizando un orden de memoria relajado. El valor no se modifica de ninguna manera, pero ten en cuenta que no hay garantía de que permanezca así.

Véase también storeRelaxed() y loadAcquire().

void QAtomicPointer::storeRelaxed(T *newValue)

Almacena atómicamente el valor newValue en este tipo atómico, utilizando un orden de memoria relajado.

Véase también storeRelease() y loadRelaxed().

void QAtomicPointer::storeRelease(T *newValue)

Almacena atómicamente el valor newValue en este tipo atómico, utilizando la ordenación de memoria "Release".

Véase también storeRelaxed() y loadRelaxed().

bool QAtomicPointer::testAndSetAcquire(T *expectedValue, T *newValue)

Pruebas atómicas.

Nota: Si utiliza esta función en un bucle, considere utilizar en su lugar la sobrecarga con el argumento adicional T *&currentValue, que evita el load() adicional en caso de fallo.

Si el valor actual de este QAtomicPointer es el expectedValue, las funciones test-and-set asignan el newValue a este QAtomicPointer y devuelven true. Si los valores no son iguales, esta función no hace nada y devuelve false.

Esta función utiliza la semántica de adquirir memory ordering, que asegura que el acceso a memoria que sigue a la operación atómica (en el orden del programa) no puede ser reordenado antes de la operación atómica.

bool QAtomicPointer::testAndSetAcquire(T *expectedValue, T *newValue, T *&currentValue)

Test-and-set atómico.

Si el valor actual de este QAtomicPointer es el expectedValue, las funciones test-and-set asignan el newValue a este QAtomicPointer y devuelven true. Si los valores no son los mismos, las funciones cargan el valor actual de este QAtomicPointer en currentValue y devuelven false.

Esta función utiliza la semántica acquire memory ordering, que garantiza que el acceso a la memoria que sigue a la operación atómica (en el orden del programa) no puede reordenarse antes de la operación atómica. Si el test-and-set falla, el currentValue se carga con la semántica acquire memory ordering.

bool QAtomicPointer::testAndSetOrdered(T *expectedValue, T *newValue)

Pruebas atómicas.

Nota: Si utiliza esta función en un bucle, considere utilizar en su lugar la sobrecarga con el argumento adicional T *&currentValue, que evita el load() adicional en caso de fallo.

Si el valor actual de este QAtomicPointer es el expectedValue, las funciones test-and-set asignan el newValue a este QAtomicPointer y devuelven true. Si los valores no son iguales, esta función no hace nada y devuelve false.

Esta función utiliza la semántica memory ordering ordenada, que garantiza que el acceso a la memoria antes y después de la operación atómica (en el orden del programa) no puede reordenarse.

bool QAtomicPointer::testAndSetOrdered(T *expectedValue, T *newValue, T *&currentValue)

Test-and-set atómico.

Si el valor actual de este QAtomicPointer es el expectedValue, las funciones test-and-set asignan el newValue a este QAtomicPointer y devuelven true. Si los valores no son los mismos, las funciones cargan el valor actual de este QAtomicPointer en currentValue y devuelven false.

Esta función utiliza la semántica memory ordering ordenada, que garantiza que el acceso a la memoria antes y después de la operación atómica (en el orden del programa) no puede reordenarse. Si el test-and-set falla, el currentValue se carga con la semántica acquire memory ordering.

bool QAtomicPointer::testAndSetRelaxed(T *expectedValue, T *newValue)

Pruebas atómicas.

Nota: Si utiliza esta función en un bucle, considere utilizar en su lugar la sobrecarga con el argumento adicional T *&currentValue, que evita el load() adicional en caso de fallo.

Si el valor actual de este QAtomicPointer es el expectedValue, las funciones test-and-set asignan el newValue a este QAtomicPointer y devuelven true. Si los valores no son iguales, esta función no hace nada y devuelve false.

Esta función utiliza la semántica relajada de memory ordering, dejando que el compilador y el procesador reordenen libremente los accesos a memoria.

bool QAtomicPointer::testAndSetRelaxed(T *expectedValue, T *newValue, T *&currentValue)

Test-and-set atómico.

Si el valor actual de este QAtomicPointer es el expectedValue, las funciones test-and-set asignan el newValue a este QAtomicPointer y devuelven true. Si los valores no son los mismos, las funciones cargan el valor actual de este QAtomicPointer en currentValue y devuelven false.

Esta función utiliza una semántica relajada de memory ordering, lo que permite al compilador y al procesador reordenar libremente los accesos a la memoria. Si el test-and-set falla, el currentValue se carga con semántica relajada memory ordering.

bool QAtomicPointer::testAndSetRelease(T *expectedValue, T *newValue)

Pruebas atómicas.

Nota: Si utiliza esta función en un bucle, considere utilizar en su lugar la sobrecarga con el argumento adicional T *&currentValue, que evita el load() adicional en caso de fallo.

Si el valor actual de este QAtomicPointer es el expectedValue, las funciones test-and-set asignan el newValue a este QAtomicPointer y devuelven true. Si los valores no son iguales, esta función no hace nada y devuelve false.

Esta función utiliza la semántica release memory ordering, que garantiza que el acceso a la memoria antes de la operación atómica (en el orden del programa) no puede ser reordenado después de la operación atómica.

bool QAtomicPointer::testAndSetRelease(T *expectedValue, T *newValue, T *&currentValue)

Test-and-set atómico.

Si el valor actual de este QAtomicPointer es el expectedValue, las funciones test-and-set asignan el newValue a este QAtomicPointer y devuelven true. Si los valores no son los mismos, las funciones cargan el valor actual de este QAtomicPointer en currentValue y devuelven false.

Esta función utiliza la semántica release memory ordering, que garantiza que el acceso a la memoria antes de la operación atómica (en el orden del programa) no puede reordenarse después de la operación atómica. Si el test-and-set falla, el currentValue se carga con semántica relajada memory ordering.

[noexcept] QAtomicPointer<T> &QAtomicPointer::operator=(const QAtomicPointer<T> &other)

Asigna other a este QAtomicPointer y devuelve una referencia a este QAtomicPointer.

Documentación de macros

Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_ALWAYS_NATIVE

Esta macro se define si y sólo si su procesador soporta fetch-and-add atómico en punteros.

Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_NOT_NATIVE

Esta macro se define cuando el hardware no soporta fetch-and-add atómico en punteros.

Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_SOMETIMES_NATIVE

Esta macro se define cuando sólo ciertas generaciones del procesador soportan fetch-and-add atómico en punteros. Utilice la función QAtomicPointer::isFetchAndAddNative() para comprobar qué soporta su procesador.

Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_WAIT_FREE

Esta macro se define junto con Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_ALWAYS_NATIVE para indicar que la obtención y adición atómica de punteros no requiere espera.

Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_ALWAYS_NATIVE

Esta macro se define si y sólo si su procesador soporta fetch-and-store atómico en punteros.

Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_NOT_NATIVE

Esta macro se define cuando el hardware no soporta fetch-and-store atómico en punteros.

Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_SOMETIMES_NATIVE

Esta macro se define cuando sólo ciertas generaciones del procesador soportan fetch-and-store atómico sobre punteros. Utilice la función QAtomicPointer::isFetchAndStoreNative() para comprobar qué soporta su procesador.

Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_WAIT_FREE

Esta macro se define junto con Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_ALWAYS_NATIVE para indicar que el fetch-and-store atómico sobre punteros está libre de esperas.

Q_ATOMIC_POINTER_TEST_AND_SET_IS_ALWAYS_NATIVE

Esta macro se define si y sólo si su procesador soporta atomic test-and-set en punteros.

Q_ATOMIC_POINTER_TEST_AND_SET_IS_NOT_NATIVE

Esta macro se define cuando el hardware no soporta test-and-set atómico en punteros.

Q_ATOMIC_POINTER_TEST_AND_SET_IS_SOMETIMES_NATIVE

Esta macro se define cuando sólo ciertas generaciones del procesador soportan atomic test-and-set en punteros. Utilice la función QAtomicPointer::isTestAndSetNative() para comprobar qué soporta su procesador.

Q_ATOMIC_POINTER_TEST_AND_SET_IS_WAIT_FREE

Esta macro se define junto con Q_ATOMIC_POINTER_TEST_AND_SET_IS_ALWAYS_NATIVE para indicar que el test-and-set atómico sobre punteros está libre de esperas.

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