Sur cette page

QAtomicPointer Class

template <typename T> class QAtomicPointer

La classe QAtomicPointer est une classe modèle qui fournit des opérations atomiques indépendantes de la plate-forme sur les pointeurs. Plus d'informations...

En-tête : #include <QAtomicPointer>
CMake : find_package(Qt6 REQUIRED COMPONENTS Core)
target_link_libraries(mytarget PRIVATE Qt6::Core)
qmake : QT += core

Fonctions publiques

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)

Membres publics statiques

Macros

Description détaillée

Pour les opérations atomiques sur les entiers, voir la classe QAtomicInteger.

Une opération atomique est une opération complexe qui se termine sans interruption. La classe QAtomicPointer permet d'effectuer des opérations atomiques de type test-and-set, fetch-and-store et fetch-and-add pour les pointeurs.

L'API atomique

Ordonnancement de la mémoire

QAtomicPointer fournit plusieurs implémentations des fonctions atomiques test-and-set, fetch-and-store et fetch-and-add. Chaque implémentation définit une sémantique d'ordre mémoire qui décrit comment les accès mémoire entourant l'instruction atomique sont exécutés par le processeur. Étant donné que de nombreuses architectures modernes permettent une exécution hors ordre et un ordonnancement de la mémoire, il est nécessaire d'utiliser la bonne sémantique pour garantir que votre application fonctionne correctement sur tous les processeurs.

  • Relaxed - l'ordre de la mémoire n'est pas spécifié, ce qui permet au compilateur et au processeur de réorganiser librement les accès à la mémoire.
  • Acquérir - l'accès à la mémoire qui suit l'opération atomique (dans l'ordre du programme) ne peut pas être réordonné avant l'opération atomique.
  • Release - l'accès à la mémoire avant l'opération atomique (dans l'ordre du programme) ne peut pas être réordonné après l'opération atomique.
  • Ordered - la même sémantique Acquire et Release combinée.

Test et réglage

Si la valeur actuelle du QAtomicPointer est une valeur attendue, les fonctions test-and-set attribuent une nouvelle valeur au QAtomicPointer et renvoient true. Si les valeurs ne sont pas les mêmes, ces fonctions ne font rien et renvoient false. Cette opération correspond au code suivant :

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

Il existe 4 fonctions test-and-set : testAndSetRelaxed(), testAndSetAcquire(), testAndSetRelease() et testAndSetOrdered(). Voir ci-dessus pour une explication des différentes sémantiques d'ordonnancement de la mémoire.

Récupérer et stocker

Les fonctions d'extraction et de stockage atomiques lisent la valeur actuelle du QAtomicPointer, puis lui attribuent une nouvelle valeur, en renvoyant la valeur d'origine. Cette opération correspond au code suivant :

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

Il existe 4 fonctions d'extraction et de stockage : fetchAndStoreRelaxed(), fetchAndStoreAcquire(), fetchAndStoreRelease() et fetchAndStoreOrdered(). Voir ci-dessus pour une explication des différentes sémantiques d'ordonnancement de la mémoire.

Récupérer et ajouter

Les fonctions d'extraction et d'ajout atomiques lisent la valeur actuelle du QAtomicPointer, puis ajoutent la valeur donnée à la valeur actuelle, en renvoyant la valeur d'origine. Cette opération correspond au code suivant :

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

Il existe 4 fonctions de récupération et d'ajout : fetchAndAddRelaxed(), fetchAndAddAcquire(), fetchAndAddRelease() et fetchAndAddOrdered(). Voir ci-dessus pour une explication des différentes sémantiques d'ordonnancement de la mémoire.

Tests de fonctionnalités pour l'API atomique

Fournir une API atomique indépendante de la plate-forme qui fonctionne sur tous les processeurs est un défi. L'API fournie par QAtomicPointer est garantie pour fonctionner de manière atomique sur tous les processeurs. Cependant, comme tous les processeurs ne prennent pas en charge toutes les opérations fournies par QAtomicPointer, il est nécessaire d'exposer des informations sur le processeur.

Vous pouvez vérifier au moment de la compilation quelles fonctionnalités sont prises en charge par votre matériel à l'aide de diverses macros. Celles-ci vous indiqueront si votre matériel prend toujours, parfois ou pas du tout en charge une opération particulière. Les macros ont la forme Q_ATOMIC_POINTER_OPERATION_IS_HOW_NATIVE. OPERATION est l'une des valeurs suivantes : TEST_AND_SET, FETCH_AND_STORE, ou FETCH_AND_ADD, et HOW est l'une des valeurs suivantes : ALWAYS, SOMETIMES, ou NOT. Il y aura toujours exactement une macro définie par opération. Par exemple, si Q_ATOMIC_POINTER_TEST_AND_SET_IS_ALWAYS_NATIVE est défini, ni Q_ATOMIC_POINTER_TEST_AND_SET_IS_SOMETIMES_NATIVE ni Q_ATOMIC_POINTER_TEST_AND_SET_IS_NOT_NATIVE ne le seront.

Une opération qui se termine en temps constant est dite sans attente. Ces opérations ne sont pas mises en œuvre à l'aide de verrous ou de boucles d'aucune sorte. Pour les opérations atomiques qui sont toujours prises en charge et qui sont sans attente, Qt définit l'option Q_ATOMIC_POINTER_OPERATION_IS_WAIT_FREE en plus de l'option Q_ATOMIC_POINTER_OPERATION_IS_ALWAYS_NATIVE.

Dans les cas où une opération atomique n'est supportée que par les nouvelles générations de processeurs, QAtomicPointer fournit également un moyen de vérifier à l'exécution ce que votre matériel supporte avec les fonctions isTestAndSetNative(), isFetchAndStoreNative(), et isFetchAndAddNative(). Les implémentations sans attente peuvent être détectées à l'aide des fonctions isTestAndSetWaitFree(), isFetchAndStoreWaitFree() et isFetchAndAddWaitFree().

Vous trouverez ci-dessous une liste complète de toutes les macros caractéristiques de QAtomicPointer :

Voir également QAtomicInteger et qYieldCpu().

Documentation des fonctions membres

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

Construit un QAtomicPointer avec l'adresse value.

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

Construit une copie de other.

T *QAtomicPointer::fetchAndAddAcquire(qptrdiff valueToAdd)

Récupération et ajout atomiques.

Lit la valeur actuelle de ce QAtomicPointer, puis ajoute valueToAdd à la valeur actuelle, en renvoyant la valeur originale.

Cette fonction utilise la sémantique acquire memory ordering, qui garantit que l'accès à la mémoire suivant l'opération atomique (dans l'ordre du programme) ne peut pas être réorganisé avant l'opération atomique.

T *QAtomicPointer::fetchAndAddOrdered(qptrdiff valueToAdd)

Récupération et ajout atomiques.

Lit la valeur actuelle de ce QAtomicPointer, puis ajoute valueToAdd à la valeur actuelle, en renvoyant la valeur d'origine.

Cette fonction utilise la sémantique memory ordering ordonnée, qui garantit que l'accès à la mémoire avant et après l'opération atomique (dans l'ordre du programme) ne peut pas être réordonné.

T *QAtomicPointer::fetchAndAddRelaxed(qptrdiff valueToAdd)

Récupération et ajout atomiques.

Lit la valeur actuelle de ce QAtomicPointer, puis ajoute valueToAdd à la valeur actuelle, en renvoyant la valeur originale.

Cette fonction utilise la sémantique relâchée de memory ordering, ce qui permet au compilateur et au processeur de réorganiser librement les accès à la mémoire.

T *QAtomicPointer::fetchAndAddRelease(qptrdiff valueToAdd)

Récupération et ajout atomiques.

Lit la valeur actuelle de ce QAtomicPointer, puis ajoute valueToAdd à la valeur actuelle, en renvoyant la valeur originale.

Cette fonction utilise la sémantique release memory ordering, qui garantit que l'accès à la mémoire avant l'opération atomique (dans l'ordre du programme) ne peut pas être réorganisé après l'opération atomique.

T *QAtomicPointer::fetchAndStoreAcquire(T *newValue)

Récupération et stockage atomiques.

Lit la valeur actuelle de ce QAtomicPointer et lui affecte le newValue, en renvoyant la valeur d'origine.

Cette fonction utilise la sémantique acquire memory ordering, qui garantit que l'accès à la mémoire suivant l'opération atomique (dans l'ordre du programme) ne peut pas être réorganisé avant l'opération atomique.

T *QAtomicPointer::fetchAndStoreOrdered(T *newValue)

Récupération et stockage atomiques.

Lit la valeur actuelle de ce QAtomicPointer, puis lui affecte le newValue, en renvoyant la valeur d'origine.

Cette fonction utilise la sémantique memory ordering ordonnée, qui garantit que l'accès à la mémoire avant et après l'opération atomique (dans l'ordre du programme) ne peut pas être réordonné.

T *QAtomicPointer::fetchAndStoreRelaxed(T *newValue)

Récupération et stockage atomiques.

Lit la valeur actuelle de ce QAtomicPointer, puis lui assigne le newValue, en renvoyant la valeur d'origine.

Cette fonction utilise la sémantique relâchée de memory ordering, ce qui permet au compilateur et au processeur de réorganiser librement les accès à la mémoire.

T *QAtomicPointer::fetchAndStoreRelease(T *newValue)

Recherche et stockage atomiques.

Lit la valeur actuelle de ce QAtomicPointer, puis lui affecte le newValue, en renvoyant la valeur d'origine.

Cette fonction utilise la sémantique release memory ordering, qui garantit que l'accès à la mémoire avant l'opération atomique (dans l'ordre du programme) ne peut pas être réorganisé après l'opération atomique.

[static constexpr] bool QAtomicPointer::isFetchAndAddNative()

Renvoie true si l'opération d'extraction et d'addition est mise en œuvre à l'aide d'instructions atomiques du processeur, false dans le cas contraire.

[static constexpr] bool QAtomicPointer::isFetchAndAddWaitFree()

Renvoie true si la recherche et l'ajout atomiques sont sans attente, false sinon.

[static constexpr] bool QAtomicPointer::isFetchAndStoreNative()

Renvoie true si la fonction d'extraction et de stockage est mise en œuvre à l'aide d'instructions atomiques du processeur, false dans le cas contraire.

[static constexpr] bool QAtomicPointer::isFetchAndStoreWaitFree()

Retourne true si la recherche et le stockage atomiques sont sans attente, false sinon.

[static constexpr] bool QAtomicPointer::isTestAndSetNative()

Renvoie true si le test-et-set est mis en œuvre à l'aide d'instructions atomiques du processeur, false dans le cas contraire.

[static constexpr] bool QAtomicPointer::isTestAndSetWaitFree()

Retourne true si le test-et-ensemble atomique est sans attente, false sinon.

T *QAtomicPointer::loadAcquire() const

Charge de manière atomique la valeur de ce site QAtomicPointer en utilisant la commande de mémoire "Acquire". La valeur n'est en aucun cas modifiée, mais il n'y a aucune garantie qu'elle le reste.

Voir aussi storeRelease() et loadRelaxed().

T *QAtomicPointer::loadRelaxed() const

Charge de manière atomique la valeur de ce QAtomicPointer en utilisant un ordre de mémoire détendu. La valeur n'est en aucun cas modifiée, mais il n'y a aucune garantie qu'elle le reste.

Voir aussi storeRelaxed() et loadAcquire().

void QAtomicPointer::storeRelaxed(T *newValue)

Enregistre de manière atomique la valeur newValue dans ce type atomique, en utilisant un ordre de mémoire détendu.

Voir aussi storeRelease() et loadRelaxed().

void QAtomicPointer::storeRelease(T *newValue)

La valeur newValue est stockée de manière atomique dans ce type atomique, en utilisant l'ordre de mémoire "Release".

Voir aussi storeRelaxed() et loadRelaxed().

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

Test et réglage atomiques.

Remarque : si vous utilisez cette fonction dans une boucle, envisagez plutôt d'utiliser la surcharge avec l'argument supplémentaire T *&currentValue, ce qui permet d'éviter la fonction load() supplémentaire en cas d'échec.

Si la valeur actuelle de ce QAtomicPointer est le expectedValue, les fonctions de test et d'établissement attribuent le newValue à ce QAtomicPointer et renvoient un résultat positif. Si les valeurs sont différentes, cette fonction ne fait rien et renvoie false.

Cette fonction utilise la sémantique acquire memory ordering, qui garantit que l'accès à la mémoire suivant l'opération atomique (dans l'ordre du programme) ne peut pas être réorganisé avant l'opération atomique.

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

Test-et-set atomique.

Si la valeur actuelle de ce QAtomicPointer est le expectedValue, les fonctions de test et de réglage attribuent le newValue à ce QAtomicPointer et renvoient le true. Si les valeurs sont différentes, les fonctions chargent la valeur actuelle de ce QAtomicPointer dans currentValue et renvoient false.

Cette fonction utilise la sémantique " acquire memory ordering ", qui garantit que l'accès à la mémoire suivant l'opération atomique (dans l'ordre du programme) ne peut pas être réorganisé avant l'opération atomique. Si le test et la mise en place échouent, l'adresse currentValue est chargée avec la sémantique " acquire memory ordering ".

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

Test et réglage atomiques.

Remarque : si vous utilisez cette fonction dans une boucle, envisagez plutôt d'utiliser la surcharge avec l'argument supplémentaire T *&currentValue, ce qui permet d'éviter la fonction load() supplémentaire en cas d'échec.

Si la valeur actuelle de ce QAtomicPointer est le expectedValue, les fonctions de test et d'établissement attribuent le newValue à ce QAtomicPointer et renvoient un résultat positif. Si les valeurs sont différentes, cette fonction ne fait rien et renvoie false.

Cette fonction utilise la sémantique memory ordering ordonnée, qui garantit que l'accès à la mémoire avant et après l'opération atomique (dans l'ordre du programme) ne peut pas être réordonné.

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

Test-et-set atomique.

Si la valeur actuelle de ce QAtomicPointer est le expectedValue, les fonctions de test et de réglage attribuent le newValue à ce QAtomicPointer et renvoient le true. Si les valeurs sont différentes, les fonctions chargent la valeur actuelle de ce QAtomicPointer dans currentValue et renvoient false.

Cette fonction utilise la sémantique memory ordering ordonnée, qui garantit que l'accès à la mémoire avant et après l'opération atomique (dans l'ordre du programme) ne peut pas être réordonné. Si le test et le réglage échouent, currentValue est chargé avec la sémantique " acquire memory ordering ".

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

Test et réglage atomiques.

Remarque : si vous utilisez cette fonction dans une boucle, envisagez plutôt d'utiliser la surcharge avec l'argument supplémentaire T *&currentValue, ce qui permet d'éviter la fonction load() supplémentaire en cas d'échec.

Si la valeur actuelle de ce QAtomicPointer est le expectedValue, les fonctions de test et d'établissement attribuent le newValue à ce QAtomicPointer et renvoient un résultat positif. Si les valeurs sont différentes, cette fonction ne fait rien et renvoie false.

Cette fonction utilise la sémantique relâchée de memory ordering, ce qui permet au compilateur et au processeur de réorganiser librement les accès à la mémoire.

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

Test-et-set atomique.

Si la valeur actuelle de ce QAtomicPointer est le expectedValue, les fonctions de test et de réglage attribuent le newValue à ce QAtomicPointer et renvoient le true. Si les valeurs sont différentes, les fonctions chargent la valeur actuelle de QAtomicPointer dans currentValue et renvoient false.

Cette fonction utilise la sémantique relâchée de memory ordering, ce qui permet au compilateur et au processeur de réorganiser librement les accès à la mémoire. Si le test et la définition échouent, la valeur de currentValue est chargée avec la sémantique relâchée de memory ordering.

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

Test et réglage atomiques.

Remarque : si vous utilisez cette fonction dans une boucle, envisagez plutôt d'utiliser la surcharge avec l'argument supplémentaire T *&currentValue, ce qui permet d'éviter la charge supplémentaire load() en cas d'échec.

Si la valeur actuelle de ce QAtomicPointer est le expectedValue, les fonctions de test et d'établissement attribuent le newValue à ce QAtomicPointer et renvoient un résultat positif. Si les valeurs sont différentes, cette fonction ne fait rien et renvoie false.

Cette fonction utilise la sémantique release memory ordering, qui garantit que l'accès à la mémoire avant l'opération atomique (dans l'ordre du programme) ne peut pas être réorganisé après l'opération atomique.

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

Test-et-set atomique.

Si la valeur actuelle de ce QAtomicPointer est le expectedValue, les fonctions de test et de réglage attribuent le newValue à ce QAtomicPointer et renvoient le true. Si les valeurs sont différentes, les fonctions chargent la valeur actuelle de ce QAtomicPointer dans currentValue et renvoient false.

Cette fonction utilise la sémantique release memory ordering, qui garantit que l'accès à la mémoire avant l'opération atomique (dans l'ordre du programme) ne peut pas être réorganisé après l'opération atomique. Si le test et la mise en place échouent, currentValue est chargé avec la sémantique relaxée memory ordering.

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

Affecte other à QAtomicPointer et renvoie une référence à QAtomicPointer.

Documentation sur les macros

Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_ALWAYS_NATIVE

Cette macro est définie si et seulement si votre processeur prend en charge l'extraction et l'ajout atomiques de pointeurs.

Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_NOT_NATIVE

Cette macro est définie lorsque le matériel ne prend pas en charge l'extraction et l'ajout atomiques sur les pointeurs.

Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_SOMETIMES_NATIVE

Cette macro est définie lorsque seules certaines générations de processeurs prennent en charge l'extraction et l'ajout atomiques de pointeurs. Utilisez la fonction QAtomicPointer::isFetchAndAddNative() pour vérifier ce que votre processeur supporte.

Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_WAIT_FREE

Cette macro est définie avec Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_ALWAYS_NATIVE pour indiquer que l'extraction et l'ajout atomiques sur les pointeurs sont sans attente.

Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_ALWAYS_NATIVE

Cette macro est définie si et seulement si votre processeur prend en charge l'extraction et le stockage atomiques sur les pointeurs.

Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_NOT_NATIVE

Cette macro est définie lorsque le matériel ne prend pas en charge l'extraction et le stockage atomiques sur les pointeurs.

Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_SOMETIMES_NATIVE

Cette macro est définie lorsque seules certaines générations de processeurs prennent en charge l'extraction et le stockage atomiques sur les pointeurs. Utilisez la fonction QAtomicPointer::isFetchAndStoreNative() pour vérifier ce que votre processeur supporte.

Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_WAIT_FREE

Cette macro est définie avec Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_ALWAYS_NATIVE pour indiquer que l'extraction et le stockage atomiques sur les pointeurs sont sans attente.

Q_ATOMIC_POINTER_TEST_AND_SET_IS_ALWAYS_NATIVE

Cette macro est définie si et seulement si votre processeur supporte le test atomique et le set sur les pointeurs.

Q_ATOMIC_POINTER_TEST_AND_SET_IS_NOT_NATIVE

Cette macro est définie lorsque le matériel ne prend pas en charge le test atomique et le réglage sur les pointeurs.

Q_ATOMIC_POINTER_TEST_AND_SET_IS_SOMETIMES_NATIVE

Cette macro est définie lorsque seules certaines générations de processeurs prennent en charge le test atomique et le réglage des pointeurs. Utilisez la fonction QAtomicPointer::isTestAndSetNative() pour vérifier ce que votre processeur supporte.

Q_ATOMIC_POINTER_TEST_AND_SET_IS_WAIT_FREE

Cette macro est définie avec Q_ATOMIC_POINTER_TEST_AND_SET_IS_ALWAYS_NATIVE pour indiquer que le test atomique sur les pointeurs est sans attente.

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