En esta página

QAtomicPointer Class

template <typename T> class QAtomicPointer

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

Encabezado: #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

Macros

Descripción detallada

Para operaciones atómicas con números enteros, consulta la clase ` QAtomicInteger `.

Una operación atómica es una operación compleja que se completa sin interrupciones. La clase `QAtomicPointer` proporciona operaciones atómicas de «comprobar y establecer», «obtener y almacenar» y «obtener y sumar» para punteros. El parámetro de plantilla ` T ` especifica el tipo al que apunta el puntero.

La API atómica

Orden de la memoria

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

  • Relajada: el orden de la memoria no está especificado, lo que permite al compilador y al procesador reordenar libremente los accesos a la memoria.
  • «Acquire»: los accesos a la memoria que siguen a la operación atómica (en el orden del programa) no pueden reordenarse antes de la operación atómica.
  • Release: los accesos a la memoria anteriores a la operación atómica (en el orden del programa) no pueden reordenarse después de la operación atómica.
  • Ordenado: combina las semánticas de «Adquirir» y «Liberar».

Prueba y establecimiento

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

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

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

Recuperación y almacenamiento

Las funciones atómicas de lectura y escritura leen el valor actual del QAtomicPointer y, a continuación, le asignan un nuevo valor, devolviendo el valor original. Esta operación equivale al siguiente código:

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

Hay cuatro funciones de lectura y almacenamiento: fetchAndStoreRelaxed(), fetchAndStoreAcquire(), fetchAndStoreRelease() y fetchAndStoreOrdered(). Véase más arriba una explicación de las diferentes semánticas de ordenación de la memoria.

Lectura y suma

Las funciones atómicas de lectura y suma leen el valor actual del QAtomicPointer y, a continuación, suman 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 cuatro funciones de lectura y suma: fetchAndAddRelaxed(), fetchAndAddAcquire(), fetchAndAddRelease() y fetchAndAddOrdered(). Véase más arriba una explicación de las diferentes semánticas de ordenación de la memoria.

Pruebas de funcionalidad para la API atómica

Ofrecer una API atómica independiente de la plataforma que funcione en todos los procesadores supone un reto. Se garantiza que la API proporcionada por QAtomicPointer funciona de forma atómica en todos los procesadores. Sin embargo, dado que no todos los procesadores implementan soporte para todas las operaciones proporcionadas por QAtomicPointer, es necesario exponer información sobre el procesador.

Se puede comprobar en tiempo de compilación qué características son compatibles con el hardware mediante diversas macros. Estas indicarán si el hardware admite una operación concreta siempre, a veces o en ningún caso. Las macros tienen la formaQ_ATOMIC_POINTER_OPERATION_IS_HOW_NATIVE. OPERATION puede ser TEST_AND_SET, FETCH_AND_STORE o FETCH_AND_ADD, y HOW puede ser ALWAYS, SOMETIMES o NOT. 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.

Se dice que una operación que se completa en tiempo constante es «sin espera» (wait-free). Dichas operaciones no se implementan utilizando bloqueos ni bucles de ningún tipo. Para las operaciones atómicas que siempre son compatibles y que no implican espera, Qt defineQ_ATOMIC_POINTER_OPERATION_IS_WAIT_FREE además deQ_ATOMIC_POINTER_OPERATION_IS_ALWAYS_NATIVE.

En los casos en que una operación atómica solo sea compatible con las generaciones más recientes de procesadores, QAtomicPointer también ofrece una forma de comprobar en tiempo de ejecución qué es lo que admite el hardware mediante 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 características de QAtomicPointer:

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

Documentación de las funciones de miembro

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

Crea un `QAtomicPointer` con el ` value` indicado.

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

Crea una copia de other.

T *QAtomicPointer::fetchAndAddAcquire(qptrdiff valueToAdd)

Operación atómica de lectura y suma.

Lee el valor actual de este QAtomicPointer y, a continuación, suma valueToAdd al valor actual, devolviendo el valor original.

Esta función utiliza la semántica «acquire- memory ordering », que garantiza que los accesos a la memoria que siguen a la operación atómica (en el orden del programa) no puedan reordenarse antes de dicha operación.

T *QAtomicPointer::fetchAndAddOrdered(qptrdiff valueToAdd)

Operación atómica de lectura y suma.

Lee el valor actual de este QAtomicPointer y, a continuación, suma valueToAdd al valor actual, devolviendo el valor original.

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

T *QAtomicPointer::fetchAndAddRelaxed(qptrdiff valueToAdd)

Operación atómica de lectura y suma.

Lee el valor actual de este « QAtomicPointer » y, a continuación, suma valueToAdd al valor actual, devolviendo el valor original.

Esta función utiliza la 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)

Operación atómica de lectura y suma.

Lee el valor actual de este QAtomicPointer y, a continuación, suma 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 anterior a la operación atómica (en el orden del programa) no pueda reordenarse después de la operación atómica.

T *QAtomicPointer::fetchAndStoreAcquire(T *newValue)

Operación atómica de lectura y escritura.

Lee el valor actual de este QAtomicPointer y, a continuación, le asigna el newValue, devolviendo el valor original.

Esta función utiliza la semántica «acquire- memory ordering », que garantiza que los accesos a la memoria posteriores a la operación atómica (en el orden del programa) no puedan reordenarse antes de dicha operación.

T *QAtomicPointer::fetchAndStoreOrdered(T *newValue)

Operación atómica de lectura y escritura.

Lee el valor actual de este QAtomicPointer y, a continuación, le asigna el newValue, devolviendo el valor original.

Esta función utiliza la semántica de « memory ordering » ordenada, lo que garantiza que los accesos a la memoria anteriores y posteriores a la operación atómica (en el orden del programa) no puedan reordenarse.

T *QAtomicPointer::fetchAndStoreRelaxed(T *newValue)

Operación atómica de lectura y escritura.

Lee el valor actual de este ` QAtomicPointer ` y, a continuación, le asigna el ` newValue`, devolviendo el valor original.

Esta función utiliza la 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)

Operación atómica de lectura y escritura.

Lee el valor actual de este QAtomicPointer y, a continuación, 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 anterior a la operación atómica (en el orden del programa) no pueda reordenarse después de la operación atómica.

[static constexpr] bool QAtomicPointer::isFetchAndAddNative()

Devuelve « true » si «fetch-and-add» se ha implementado mediante instrucciones atómicas del procesador; en caso contrario, devuelve «false».

[static constexpr] bool QAtomicPointer::isFetchAndAddWaitFree()

Devuelve ` true ` si la operación «fetch-and-add» atómica no implica espera; en caso contrario, devuelve `false`.

[static constexpr] bool QAtomicPointer::isFetchAndStoreNative()

Devuelve « true » si la instrucción «fetch-and-store» se implementa mediante instrucciones atómicas del procesador; en caso contrario, devuelve «false».

[static constexpr] bool QAtomicPointer::isFetchAndStoreWaitFree()

Devuelve « true » si la operación atómica «fetch-and-store» no implica espera; en caso contrario, devuelve «false».

[static constexpr] bool QAtomicPointer::isTestAndSetNative()

Devuelve « true » si «test-and-set» se implementa mediante instrucciones atómicas del procesador; en caso contrario, devuelve «false».

[static constexpr] bool QAtomicPointer::isTestAndSetWaitFree()

Devuelve ` true ` si la operación «test-and-set» atómica es «wait-free»; en caso contrario, devuelve `false`.

T *QAtomicPointer::loadAcquire() const

Carga de forma atómica el valor de este QAtomicPointer utilizando el orden de memoria «Acquire». El valor no se modifica en modo alguno, pero ten en cuenta que no hay garantía de que siga siendo así.

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

T *QAtomicPointer::loadRelaxed() const

Carga de forma atómica 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 siga siendo así.

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

void QAtomicPointer::storeRelaxed(T *newValue)

Almacena de forma atómica el valor de « 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 de forma atómica el valor de « newValue » en este tipo atómico, utilizando el orden de memoria «Release».

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

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

Prueba y establecimiento atómicos.

Nota: Si utilizas esta función en un bucle, plantéate utilizar en su lugar la sobrecarga con el argumento adicional T *&currentValue, lo que evita la llamada extra a load() 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 coinciden, esta función no realiza ninguna acción y devuelve ` false`.

Esta función utiliza la semántica «adquirir- memory ordering », que garantiza que el acceso a la memoria posterior a la operación atómica (en el orden del programa) no pueda reordenarse antes de la operación atómica.

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

Prueba y ajuste atómico.

Si el valor actual de este QAtomicPointer es el expectedValue, las funciones de comprobación y asignación asignan el newValue a este QAtomicPointer y devuelven true. Si los valores no coinciden, las funciones cargan el valor actual de este QAtomicPointer en currentValue y devuelven false.

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

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

Prueba y establecimiento atómico.

Nota: Si utilizas esta función en un bucle, plantéate utilizar en su lugar la sobrecarga con el argumento adicional ` T *&currentValue `, lo que evita la llamada adicional a `load()` en caso de fallo.

Si el valor actual de este ` QAtomicPointer ` es ` expectedValue`, las funciones «comparar y asignar» asignan ` newValue ` a este ` QAtomicPointer ` y devuelven `true`. Si los valores no coinciden, esta función no realiza ninguna acción y devuelve ` false`.

Esta función utiliza la semántica « 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 pueda reordenarse.

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

Prueba y establecimiento atómico.

Si el valor actual de este QAtomicPointer es el expectedValue, las funciones de prueba y asignación asignan el newValue a este QAtomicPointer y devuelven true. Si los valores no son iguales, las funciones cargan el valor actual de este QAtomicPointer en currentValue y devuelven false.

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

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

Prueba y establecimiento atómico.

Nota: Si utilizas esta función en un bucle, plantéate utilizar en su lugar la sobrecarga con el argumento adicional ` T *&currentValue `, lo que evita la llamada adicional a `load()` en caso de fallo.

Si el valor actual de este ` QAtomicPointer ` es el ` expectedValue`, las funciones de comprobación y asignación asignan el ` newValue ` a este ` QAtomicPointer ` y devuelven `true`. Si los valores no coinciden, esta función no realiza ninguna acción y devuelve ` false`.

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

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

Prueba y establecimiento 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 coinciden, las funciones cargan el valor actual de este « QAtomicPointer » en « currentValue » y devuelven « false ».

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

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

Prueba y establecimiento atómicos.

Nota: Si utilizas esta función en un bucle, considera la posibilidad de utilizar en su lugar la sobrecarga con el argumento adicional ` T *&currentValue `, lo que evita la llamada adicional a `load()` 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 coinciden, esta función no realiza ninguna acción y devuelve ` false`.

Esta función utiliza la semántica « memory ordering », que garantiza que el acceso a la memoria anterior a la operación atómica (en el orden del programa) no pueda reordenarse tras la operación atómica.

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

Prueba y establecimiento atómico.

Si el valor actual de este QAtomicPointer es el expectedValue, las funciones de prueba y asignación asignan el newValue a este QAtomicPointer y devuelven true. Si los valores no coinciden, las funciones cargan el valor actual de este QAtomicPointer en currentValue y devuelven false.

Esta función utiliza la semántica «release» memory ordering, lo que garantiza que el acceso a la memoria anterior a la operación atómica (en el orden del programa) no pueda reordenarse tras la operación atómica. Si la operación «test-and-set» falla, el currentValue se carga con la semántica «relaxed» 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 solo si el procesador admite operaciones atómicas de lectura y suma con punteros.

Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_NOT_NATIVE

Esta macro se define cuando el hardware no admite operaciones atómicas de lectura y adición en punteros.

Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_SOMETIMES_NATIVE

Esta macro se define cuando solo determinadas generaciones del procesador admiten la operación atómica «fetch-and-add» con punteros. Utiliza la función ` QAtomicPointer::isFetchAndAddNative()` para comprobar qué funciones admite tu 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 operación atómica de lectura y adición en punteros no implica espera.

Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_ALWAYS_NATIVE

Esta macro se define si, y solo si, tu procesador admite operaciones atómicas de lectura y escritura en punteros.

Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_NOT_NATIVE

Esta macro se define cuando el hardware no admite operaciones atómicas de lectura y escritura en punteros.

Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_SOMETIMES_NATIVE

Esta macro se define cuando solo determinadas generaciones del procesador admiten operaciones atómicas de lectura y escritura en punteros. Utiliza la función ` QAtomicPointer::isFetchAndStoreNative()` para comprobar qué funciones admite tu 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 la operación atómica de lectura y escritura en punteros no implica espera.

Q_ATOMIC_POINTER_TEST_AND_SET_IS_ALWAYS_NATIVE

Esta macro se define si y solo si el procesador admite la operación atómica «test-and-set» en punteros.

Q_ATOMIC_POINTER_TEST_AND_SET_IS_NOT_NATIVE

Esta macro se define cuando el hardware no admite la operación atómica «test-and-set» en punteros.

Q_ATOMIC_POINTER_TEST_AND_SET_IS_SOMETIMES_NATIVE

Esta macro se define cuando solo determinadas generaciones del procesador admiten la operación «test-and-set» atómica en punteros. Utiliza la función ` QAtomicPointer::isTestAndSetNative()` para comprobar qué funciones admite tu 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 la operación atómica «test-and-set» sobre punteros no implica espera.

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