Back to Qt.io
Contact Us Blog Download Qt

QAtomicPointer Class

template <typename T> class QAtomicPointer

Die Klasse QAtomicPointer ist eine Vorlagenklasse, die plattformunabhängige atomare Operationen mit Zeigern ermöglicht. Mehr...

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

Öffentliche Funktionen

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 testAndSetOrdered(T *expectedValue, T *newValue)
bool testAndSetRelaxed(T *expectedValue, T *newValue)
bool testAndSetRelease(T *expectedValue, T *newValue)
QAtomicPointer<T> &operator=(const QAtomicPointer<T> &other)

Statische öffentliche Mitglieder

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

Makros

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

Detaillierte Beschreibung

Für atomare Operationen auf Ganzzahlen siehe die Klasse QAtomicInteger.

Eine atomare Operation ist eine komplexe Operation, die ohne Unterbrechung abgeschlossen wird. Die Klasse QAtomicPointer bietet atomares Testen-und-Setzen, Holen-und-Speichern und Holen-und-Hinzufügen für Zeiger.

Die atomare API

Speicherordnung

QAtomicPointer bietet mehrere Implementierungen der atomaren Funktionen test-and-set, fetch-and-store und fetch-and-add. Jede Implementierung definiert eine Speicherordnungssemantik, die beschreibt, wie Speicherzugriffe rund um die atomare Anweisung vom Prozessor ausgeführt werden. Da viele moderne Architekturen eine Ausführung außerhalb der Reihenfolge und eine Speicherordnung zulassen, ist die Verwendung der richtigen Semantik erforderlich, um sicherzustellen, dass Ihre Anwendung auf allen Prozessoren ordnungsgemäß funktioniert.

  • Relaxed - die Speicherreihenfolge ist nicht spezifiziert und überlässt es dem Compiler und dem Prozessor, die Reihenfolge der Speicherzugriffe frei zu wählen.
  • Acquire - Speicherzugriffe nach der atomaren Operation (in Programmreihenfolge) dürfen vor der atomaren Operation nicht neu geordnet werden.
  • Release - Speicherzugriffe vor der atomaren Operation (in der Programmreihenfolge) dürfen nach der atomaren Operation nicht neu geordnet werden.
  • Geordnet - die gleiche Semantik von Acquire und Release kombiniert.

Testen und Einstellen

Wenn der aktuelle Wert des QAtomicPointers ein erwarteter Wert ist, weisen die test-and-set Funktionen dem QAtomicPointer einen neuen Wert zu und geben true zurück. Wenn die Werte not gleich sind, tun diese Funktionen nichts und geben false zurück. Dieser Vorgang entspricht dem folgenden Code:

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

Es gibt 4 test-and-set Funktionen: testAndSetRelaxed(), testAndSetAcquire(), testAndSetRelease() und testAndSetOrdered(). Siehe oben für eine Erklärung der verschiedenen Speicherordnungssemantiken.

Holen-und-Speichern

Die atomaren fetch-and-store-Funktionen lesen den aktuellen Wert des QAtomicPointers, weisen ihm dann einen neuen Wert zu und geben den ursprünglichen Wert zurück. Diese Operation entspricht dem folgenden Code:

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

Es gibt 4 fetch-and-store Funktionen: fetchAndStoreRelaxed(), fetchAndStoreAcquire(), fetchAndStoreRelease() und fetchAndStoreOrdered(). Siehe oben für eine Erklärung der verschiedenen Speicherordnungssemantiken.

Fetch-and-add

Die atomaren fetch-and-add-Funktionen lesen den aktuellen Wert des QAtomicPointers und fügen dann den angegebenen Wert zum aktuellen Wert hinzu und geben den ursprünglichen Wert zurück. Diese Operation entspricht dem folgenden Code:

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

Es gibt 4 fetch-and-add Funktionen: fetchAndAddRelaxed(), fetchAndAddAcquire(), fetchAndAddRelease(), und fetchAndAddOrdered(). Siehe oben für eine Erklärung der verschiedenen Speicherordnungssemantiken.

Funktionstests für die atomare API

Die Bereitstellung einer plattformunabhängigen atomaren API, die auf allen Prozessoren funktioniert, ist eine Herausforderung. Die von QAtomicPointer bereitgestellte API funktioniert garantiert atomar auf allen Prozessoren. Da jedoch nicht alle Prozessoren die Unterstützung für jede von QAtomicPointer bereitgestellte Operation implementieren, ist es notwendig, Informationen über den Prozessor offenzulegen.

Sie können zur Kompilierzeit überprüfen, welche Funktionen auf Ihrer Hardware unterstützt werden, indem Sie verschiedene Makros verwenden. Diese sagen Ihnen, ob Ihre Hardware eine bestimmte Operation immer, manchmal oder gar nicht unterstützt. Die Makros haben die Form Q_ATOMIC_POINTER_OPERATION_IS_HOW_NATIVE. OPERATION ist einer der Werte TEST_AND_SET, FETCH_AND_STORE oder FETCH_AND_ADD, und HOW ist einer der Werte ALWAYS, SOMETIMES oder NOT. Es wird immer genau ein definiertes Makro pro Operation geben. Wenn zum Beispiel Q_ATOMIC_POINTER_TEST_AND_SET_IS_ALWAYS_NATIVE definiert ist, werden weder Q_ATOMIC_POINTER_TEST_AND_SET_IS_SOMETIMES_NATIVE noch Q_ATOMIC_POINTER_TEST_AND_SET_IS_NOT_NATIVE definiert.

Eine Operation, die in konstanter Zeit abgeschlossen wird, wird als wartungsfrei bezeichnet. Solche Operationen werden nicht mit Sperren oder Schleifen jeglicher Art implementiert. Für atomare Operationen, die immer unterstützt werden und wartungsfrei sind, definiert Qt die Q_ATOMIC_POINTER_OPERATION_IS_WAIT_FREE zusätzlich zu Q_ATOMIC_POINTER_OPERATION_IS_ALWAYS_NATIVE.

In Fällen, in denen eine atomare Operation nur in neueren Generationen des Prozessors unterstützt wird, bietet QAtomicPointer auch eine Möglichkeit, zur Laufzeit zu prüfen, was Ihre Hardware mit den Funktionen isTestAndSetNative(), isFetchAndStoreNative() und isFetchAndAddNative() unterstützt. Wartefreie Implementierungen können mit den Funktionen isTestAndSetWaitFree(), isFetchAndStoreWaitFree() und isFetchAndAddWaitFree() erkannt werden.

Im Folgenden finden Sie eine vollständige Liste aller Funktionsmakros für QAtomicPointer:

Siehe auch QAtomicInteger und qYieldCpu().

Dokumentation der Mitgliedsfunktionen

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

Konstruiert einen QAtomicPointer mit dem angegebenen value.

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

Konstruiert eine Kopie von other.

T *QAtomicPointer::fetchAndAddAcquire(qptrdiff valueToAdd)

Atomares Holen und Hinzufügen.

Liest den aktuellen Wert von QAtomicPointer und addiert dann valueToAdd zum aktuellen Wert und gibt den ursprünglichen Wert zurück.

Diese Funktion verwendet die Semantik von acquire memory ordering, die sicherstellt, dass der Speicherzugriff nach der atomaren Operation (in der Programmreihenfolge) nicht vor der atomaren Operation neu geordnet werden kann.

T *QAtomicPointer::fetchAndAddOrdered(qptrdiff valueToAdd)

Atomares Holen und Hinzufügen.

Liest den aktuellen Wert von QAtomicPointer und addiert dann valueToAdd zum aktuellen Wert und gibt den ursprünglichen Wert zurück.

Diese Funktion verwendet eine geordnete memory ordering Semantik, die sicherstellt, dass der Speicherzugriff vor und nach der atomaren Operation (in Programmreihenfolge) nicht neu geordnet werden kann.

T *QAtomicPointer::fetchAndAddRelaxed(qptrdiff valueToAdd)

Atomares Holen und Hinzufügen.

Liest den aktuellen Wert von QAtomicPointer und addiert dann valueToAdd zum aktuellen Wert und gibt den ursprünglichen Wert zurück.

Diese Funktion verwendet eine entspannte memory ordering Semantik, die es dem Compiler und dem Prozessor überlässt, die Speicherzugriffe neu zu ordnen.

T *QAtomicPointer::fetchAndAddRelease(qptrdiff valueToAdd)

Atomares Holen und Hinzufügen.

Liest den aktuellen Wert dieses QAtomicPointer und addiert dann valueToAdd zum aktuellen Wert und gibt den ursprünglichen Wert zurück.

Diese Funktion verwendet die Semantik von release memory ordering, die sicherstellt, dass der Speicherzugriff vor der atomaren Operation (in der Programmreihenfolge) nach der atomaren Operation nicht neu geordnet werden kann.

T *QAtomicPointer::fetchAndStoreAcquire(T *newValue)

Atomares Holen und Speichern.

Liest den aktuellen Wert dieses QAtomicPointer und weist ihm dann den newValue zu und gibt den ursprünglichen Wert zurück.

Diese Funktion verwendet die Semantik von acquire memory ordering, die sicherstellt, dass der Speicherzugriff nach der atomaren Operation (in der Programmreihenfolge) nicht vor der atomaren Operation neu geordnet werden kann.

T *QAtomicPointer::fetchAndStoreOrdered(T *newValue)

Atomares Holen und Speichern.

Liest den aktuellen Wert dieses QAtomicPointer und weist ihm dann den newValue zu und gibt den ursprünglichen Wert zurück.

Diese Funktion verwendet die geordnete memory ordering Semantik, die sicherstellt, dass der Speicherzugriff vor und nach der atomaren Operation (in Programmreihenfolge) nicht neu geordnet werden kann.

T *QAtomicPointer::fetchAndStoreRelaxed(T *newValue)

Atomares Holen und Speichern.

Liest den aktuellen Wert dieses QAtomicPointer und weist ihm dann den newValue zu, wobei der ursprüngliche Wert zurückgegeben wird.

Diese Funktion verwendet eine entspannte memory ordering Semantik, die es dem Compiler und dem Prozessor überlässt, die Speicherzugriffe frei zu ordnen.

T *QAtomicPointer::fetchAndStoreRelease(T *newValue)

Atomares Holen und Speichern.

Liest den aktuellen Wert dieses QAtomicPointer und weist ihm dann den newValue zu und gibt den ursprünglichen Wert zurück.

Diese Funktion verwendet die Semantik der Freigabe memory ordering, die sicherstellt, dass der Speicherzugriff vor der atomaren Operation (in der Programmreihenfolge) nach der atomaren Operation nicht neu geordnet werden kann.

[static constexpr] bool QAtomicPointer::isFetchAndAddNative()

Gibt true zurück, wenn fetch-and-add mit atomaren Prozessorbefehlen implementiert ist, andernfalls false.

[static constexpr] bool QAtomicPointer::isFetchAndAddWaitFree()

Gibt true zurück, wenn atomic fetch-and-add wartungsfrei ist, andernfalls false.

[static constexpr] bool QAtomicPointer::isFetchAndStoreNative()

Gibt true zurück, wenn fetch-and-store mit atomaren Prozessorbefehlen implementiert ist, andernfalls false.

[static constexpr] bool QAtomicPointer::isFetchAndStoreWaitFree()

Gibt true zurück, wenn atomares Holen und Speichern wartungsfrei ist, andernfalls false.

[static constexpr] bool QAtomicPointer::isTestAndSetNative()

Gibt true zurück, wenn test-and-set mit atomaren Prozessorbefehlen implementiert ist, andernfalls false.

[static constexpr] bool QAtomicPointer::isTestAndSetWaitFree()

Gibt true zurück, wenn atomic test-and-set wartungsfrei ist, andernfalls false.

T *QAtomicPointer::loadAcquire() const

Lädt atomar den Wert dieser QAtomicPointer unter Verwendung der Speicherreihenfolge "Acquire". Der Wert wird in keiner Weise verändert, aber es gibt keine Garantie, dass er so bleibt.

Siehe auch storeRelease() und loadRelaxed().

T *QAtomicPointer::loadRelaxed() const

Lädt atomar den Wert dieser QAtomicPointer unter Verwendung einer entspannten Speicheranordnung. Der Wert wird in keiner Weise verändert, aber es gibt keine Garantie, dass er so bleibt.

Siehe auch storeRelaxed() und loadAcquire().

void QAtomicPointer::storeRelaxed(T *newValue)

Speichert den Wert newValue atomar in diesem atomaren Typ, wobei eine entspannte Speicherordnung verwendet wird.

Siehe auch storeRelease() und loadRelaxed().

void QAtomicPointer::storeRelease(T *newValue)

Speichert den Wert newValue in diesem atomaren Typ unter Verwendung der Speicheranordnung "Release".

Siehe auch storeRelaxed() und loadRelaxed().

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

Atomares Testen und Setzen.

Wenn der aktuelle Wert dieses QAtomicPointer der expectedValue ist, weisen die test-and-set-Funktionen diesem QAtomicPointer den newValue zu und geben true zurück. Wenn die Werte nicht übereinstimmen, tut diese Funktion nichts und gibt false zurück.

Diese Funktion verwendet die Semantik von acquire memory ordering, die sicherstellt, dass der Speicherzugriff nach der atomaren Operation (in der Programmreihenfolge) nicht vor der atomaren Operation neu geordnet werden kann.

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

Atomares Testen und Setzen.

Wenn der aktuelle Wert dieses QAtomicPointer der expectedValue ist, weisen die test-and-set-Funktionen diesem QAtomicPointer den newValue zu und geben true zurück. Wenn die Werte nicht übereinstimmen, tut diese Funktion nichts und gibt false zurück.

Diese Funktion verwendet eine geordnete memory ordering Semantik, die sicherstellt, dass der Speicherzugriff vor und nach der atomaren Operation (in der Reihenfolge des Programms) nicht neu geordnet werden kann.

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

Atomares Testen und Setzen.

Wenn der aktuelle Wert dieses QAtomicPointer der expectedValue ist, weisen die test-and-set-Funktionen diesem QAtomicPointer den newValue zu und geben true zurück. Wenn die Werte nicht übereinstimmen, tut diese Funktion nichts und gibt false zurück.

Diese Funktion verwendet eine entspannte memory ordering Semantik, die es dem Compiler und dem Prozessor überlässt, die Speicherzugriffe frei zu ordnen.

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

Atomares Testen und Setzen.

Wenn der aktuelle Wert dieses QAtomicPointer der expectedValue ist, weisen die test-and-set-Funktionen diesem QAtomicPointer den newValue zu und geben true zurück. Wenn die Werte nicht übereinstimmen, tut diese Funktion nichts und gibt false zurück.

Diese Funktion verwendet die Semantik der Freigabe memory ordering, die sicherstellt, dass der Speicherzugriff vor der atomaren Operation (in der Programmreihenfolge) nach der atomaren Operation nicht neu geordnet werden kann.

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

Weist other dieser QAtomicPointer zu und gibt einen Verweis auf diese QAtomicPointer zurück.

Makro-Dokumentation

Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_ALWAYS_NATIVE

Dieses Makro ist nur dann definiert, wenn Ihr Prozessor atomares Fetch-and-Add auf Zeiger unterstützt.

Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_NOT_NATIVE

Dieses Makro wird definiert, wenn die Hardware kein atomares Fetch-and-Add auf Zeigern unterstützt.

Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_SOMETIMES_NATIVE

Dieses Makro wird definiert, wenn nur bestimmte Generationen des Prozessors atomares Holen und Hinzufügen auf Zeigern unterstützen. Verwenden Sie die Funktion QAtomicPointer::isFetchAndAddNative(), um zu prüfen, was Ihr Prozessor unterstützt.

Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_WAIT_FREE

Dieses Makro wird zusammen mit Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_ALWAYS_NATIVE definiert, um anzuzeigen, dass das atomare Holen und Hinzufügen von Zeigern wartungsfrei ist.

Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_ALWAYS_NATIVE

Dieses Makro ist nur dann definiert, wenn Ihr Prozessor atomares Holen und Speichern auf Zeigern unterstützt.

Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_NOT_NATIVE

Dieses Makro wird definiert, wenn die Hardware kein atomares Fetch-and-Store auf Zeigern unterstützt.

Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_SOMETIMES_NATIVE

Dieses Makro wird definiert, wenn nur bestimmte Generationen des Prozessors atomares Holen und Speichern auf Zeigern unterstützen. Verwenden Sie die Funktion QAtomicPointer::isFetchAndStoreNative(), um zu prüfen, was Ihr Prozessor unterstützt.

Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_WAIT_FREE

Dieses Makro wird zusammen mit Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_ALWAYS_NATIVE definiert, um anzuzeigen, dass das atomare Holen und Speichern auf Zeigern wartungsfrei ist.

Q_ATOMIC_POINTER_TEST_AND_SET_IS_ALWAYS_NATIVE

Dieses Makro ist nur dann definiert, wenn Ihr Prozessor atomares Testen und Setzen auf Zeiger unterstützt.

Q_ATOMIC_POINTER_TEST_AND_SET_IS_NOT_NATIVE

Dieses Makro wird definiert, wenn die Hardware kein atomares Testen und Setzen auf Zeigern unterstützt.

Q_ATOMIC_POINTER_TEST_AND_SET_IS_SOMETIMES_NATIVE

Dieses Makro wird definiert, wenn nur bestimmte Generationen des Prozessors atomares Testen und Setzen auf Zeiger unterstützen. Verwenden Sie die Funktion QAtomicPointer::isTestAndSetNative(), um zu prüfen, was Ihr Prozessor unterstützt.

Q_ATOMIC_POINTER_TEST_AND_SET_IS_WAIT_FREE

Dieses Makro wird zusammen mit Q_ATOMIC_POINTER_TEST_AND_SET_IS_ALWAYS_NATIVE definiert, um anzuzeigen, dass das atomare Testen und Setzen von Zeigern wartungsfrei ist.

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