QAtomicPointer Class
template <typename T> class QAtomicPointerQAtomicPointer 类是一个模板类,它提供与平台无关的指针原子操作。更多
头文件: | #include <QAtomicPointer> |
CMake: | find_package(Qt6 REQUIRED COMPONENTS Core) target_link_libraries(mytarget PRIVATE Qt6::Core) |
qmake: | QT += core |
- 所有成员(包括继承成员)的列表
- QAtomicPointer 属于线程类。
公共函数
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) |
静态公共成员
bool | isFetchAndAddNative() |
bool | isFetchAndAddWaitFree() |
bool | isFetchAndStoreNative() |
bool | isFetchAndStoreWaitFree() |
bool | isTestAndSetNative() |
bool | isTestAndSetWaitFree() |
宏
详细说明
有关整数的原子操作,请参阅QAtomicInteger 类。
原子操作是一种不间断完成的复杂操作。QAtomicPointer 类为指针提供了原子测试和设置、获取和存储以及获取和添加功能。
原子 API
内存排序
QAtomicPointer 为原子测试和设置、取回和存储以及取回和添加函数提供了多种实现。每种实现都定义了内存排序语义,用于描述处理器如何执行原子指令周围的内存访问。由于许多现代架构都允许无序执行和内存排序,因此使用正确的语义对于确保应用程序在所有处理器上正常运行是非常必要的。
- 宽松--未指定内存排序,让编译器和处理器自由调整内存访问顺序。
- 获取(Acquire)--原子操作之后的内存访问(按程序顺序)不得在原子操作之前重新排序。
- 释放 - 原子操作之前的内存访问(按程序顺序)不得在原子操作之后重新排序。
- 有序 - 结合相同的获取和释放语义。
测试和设置
如果 QAtomicPointer 的当前值是预期值,测试和设置函数会为 QAtomicPointer 分配一个新值并返回 true。如果值与not 相同,这些函数不会做任何操作,并返回 false。这一操作相当于以下代码:
if (currentValue == expectedValue) { currentValue = newValue; return true; } return false;
有 4 个测试和设置函数:testAndSetRelaxed(),testAndSetAcquire(),testAndSetRelease(), 和testAndSetOrdered().有关不同内存排序语义的解释,请参见上文。
取存
原子取存函数读取 QAtomicPointer 的当前值,然后分配一个新值,并返回原始值。这一操作相当于以下代码:
T *originalValue = currentValue; currentValue = newValue; return originalValue;
共有 4 个取存函数:fetchAndStoreRelaxed ()、fetchAndStoreAcquire ()、fetchAndStoreRelease ()和fetchAndStoreOrdered ()。有关不同内存排序语义的解释,请参见上文。
取加
原子取加函数读取 QAtomicPointer 的当前值,然后将给定值添加到当前值,并返回原始值。该操作相当于以下代码:
T *originalValue = currentValue; currentValue += valueToAdd; return originalValue;
共有 4 个取加函数:fetchAndAddRelaxed ()、fetchAndAddAcquire ()、fetchAndAddRelease ()和fetchAndAddOrdered ()。有关不同内存排序语义的解释,请参见上文。
原子 API 的功能测试
提供一个能在所有处理器上运行的独立于平台的原子 API 是一项挑战。QAtomicPointer 提供的 API 保证能在所有处理器上以原子方式运行。不过,由于并非所有处理器都支持 QAtomicPointer 提供的每种操作,因此有必要公开处理器的相关信息。
您可以在编译时使用各种宏来检查硬件支持哪些功能。这些宏将告诉您,您的硬件是始终支持、有时支持还是不支持特定操作。这些宏的形式为 Q_ATOMIC_POINTER_OPERATION_IS_HOW_NATIVE。OPERATION是TEST_AND_SET 、FETCH_AND_STORE 或FETCH_AND_ADD 之一,HOW是 ALWAYS、SOMETIMES 或 NOT 之一。每个操作总是有一个已定义的宏。例如,如果定义了Q_ATOMIC_POINTER_TEST_AND_SET_IS_ALWAYS_NATIVE ,则Q_ATOMIC_POINTER_TEST_AND_SET_IS_SOMETIMES_NATIVE 和Q_ATOMIC_POINTER_TEST_AND_SET_IS_NOT_NATIVE 都不会被定义。
在恒定时间内完成的操作称为无等待操作。此类操作不使用任何类型的锁或循环。对于始终支持且无需等待的原子操作,除了Q_ATOMIC_POINTER_OPERATION_IS_WAIT_FREE 之外,Qt 还定义了 Q_ATOMIC_POINTER_OPERATION_IS_ALWAYS_NATIVE。
如果只有新一代处理器才支持原子操作,QAtomicPointer 还提供了一种方法,可以在运行时使用isTestAndSetNative(),isFetchAndStoreNative() 和isFetchAndAddNative() 函数检查硬件支持哪些原子操作。使用isTestAndSetWaitFree(),isFetchAndStoreWaitFree() 和isFetchAndAddWaitFree() 函数可以检测无等待实现。
下面是 QAtomicPointer 的所有功能宏的完整列表:
- Q_ATOMIC_POINTER_TEST_AND_SET_IS_ALWAYS_NATIVE
- Q_ATOMIC_POINTER_TEST_AND_SET_IS_SOMETIMES_NATIVE
- Q_ATOMIC_POINTER_TEST_AND_SET_IS_NOT_NATIVE
- Q_ATOMIC_POINTER_TEST_AND_SET_IS_WAIT_FREE
- Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_ALWAYS_NATIVE
- Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_SOMETIMES_NATIVE
- Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_NOT_NATIVE
- Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_WAIT_FREE
- Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_ALWAYS_NATIVE
- Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_SOMETIMES_NATIVE
- Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_NOT_NATIVE
- Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_WAIT_FREE
另请参见 QAtomicInteger 和qYieldCpu()。
成员函数文档
[constexpr noexcept]
QAtomicPointer::QAtomicPointer(T *value = nullptr)
用给定的value 构建一个 QAtomicPointer。
[noexcept]
QAtomicPointer::QAtomicPointer(const QAtomicPointer<T> &other)
构造other 的副本。
T *QAtomicPointer::fetchAndAddAcquire(qptrdiff valueToAdd)
原子取加。
读取QAtomicPointer 的当前值,然后将valueToAdd 添加到当前值,返回原始值。
该函数使用获取 memory ordering 语义,确保原子操作后的内存访问(按程序顺序)不得在原子操作前重新排序。
T *QAtomicPointer::fetchAndAddOrdered(qptrdiff valueToAdd)
原子取加。
读取QAtomicPointer 的当前值,然后将valueToAdd 添加到当前值,返回原始值。
该函数使用有序 memory ordering 语义,确保原子操作前后的内存访问(按程序顺序)不得重新排序。
T *QAtomicPointer::fetchAndAddRelaxed(qptrdiff valueToAdd)
原子取加。
读取QAtomicPointer 的当前值,然后将valueToAdd 添加到当前值,返回原始值。
该函数使用宽松的 memory ordering 语义,让编译器和处理器自由地重新安排内存访问顺序。
T *QAtomicPointer::fetchAndAddRelease(qptrdiff valueToAdd)
原子取加。
读取QAtomicPointer 的当前值,然后将valueToAdd 添加到当前值,返回原始值。
该函数使用release memory ordering 语义,确保原子操作前的内存访问(按程序顺序)在原子操作后不得重新排序。
T *QAtomicPointer::fetchAndStoreAcquire(T *newValue)
原子取存。
读取该QAtomicPointer 的当前值,然后将其赋值给newValue ,返回原始值。
该函数使用获取 memory ordering 语义,确保原子操作之后的内存访问(按程序顺序)不得在原子操作之前重新排序。
T *QAtomicPointer::fetchAndStoreOrdered(T *newValue)
原子取存。
读取该QAtomicPointer 的当前值,然后将其赋值给newValue ,返回原始值。
该函数使用有序 memory ordering 语义,确保原子操作前后的内存访问(按程序顺序)不得重新排序。
T *QAtomicPointer::fetchAndStoreRelaxed(T *newValue)
原子取存。
读取QAtomicPointer 的当前值,然后将其赋值给newValue ,并返回原始值。
该函数使用宽松的 memory ordering 语义,让编译器和处理器自由地重新安排内存访问顺序。
T *QAtomicPointer::fetchAndStoreRelease(T *newValue)
原子取存。
读取该QAtomicPointer 的当前值,然后将其赋值给newValue ,返回原始值。
该函数使用release memory ordering 语义,确保原子操作前的内存访问(按程序顺序)在原子操作后不得重新排序。
[static constexpr]
bool QAtomicPointer::isFetchAndAddNative()
如果取加是使用原子处理器指令实现的,则返回true
,否则返回 false。
[static constexpr]
bool QAtomicPointer::isFetchAndAddWaitFree()
如果原子取加是免等待的,则返回true
,否则返回 false。
[static constexpr]
bool QAtomicPointer::isFetchAndStoreNative()
如果使用原子处理器指令实现取存,则返回true
,否则返回 false。
[static constexpr]
bool QAtomicPointer::isFetchAndStoreWaitFree()
如果原子取存是免等待的,则返回true
,否则返回 false。
[static constexpr]
bool QAtomicPointer::isTestAndSetNative()
如果测试和设置是使用原子处理器指令实现的,则返回true
,否则返回 false。
[static constexpr]
bool QAtomicPointer::isTestAndSetWaitFree()
如果原子测试和设置是免等待的,则返回true
,否则返回 false。
T *QAtomicPointer::loadAcquire() const
使用 "获取 "内存排序,原子加载QAtomicPointer 的值。该值不会以任何方式被修改,但请注意,并不能保证它始终如此。
另请参阅 storeRelease() 和loadRelaxed()。
T *QAtomicPointer::loadRelaxed() const
使用宽松的内存排序,原子加载QAtomicPointer 的值。该值不会以任何方式被修改,但请注意,并不能保证它始终如此。
另请参阅 storeRelaxed() 和loadAcquire()。
void QAtomicPointer::storeRelaxed(T *newValue)
使用宽松的内存排序,将newValue 值原子存储到该原子类型中。
另请参见 storeRelease() 和loadRelaxed()。
void QAtomicPointer::storeRelease(T *newValue)
使用 "释放 "内存排序,将newValue 值原子存储到该原子类型中。
另请参阅 storeRelaxed() 和loadRelaxed()。
bool QAtomicPointer::testAndSetAcquire(T *expectedValue, T *newValue)
原子测试和设置。
如果此QAtomicPointer 的当前值是expectedValue ,则测试和设置函数会将newValue 分配给此QAtomicPointer 并返回 true。如果值不相同,则该函数不会执行任何操作,并返回false
。
该函数使用获取 memory ordering 语义,确保原子操作(按程序顺序)之后的内存访问在原子操作之前不得重新排序。
bool QAtomicPointer::testAndSetOrdered(T *expectedValue, T *newValue)
原子测试和设置。
如果此QAtomicPointer 的当前值是expectedValue ,则测试和设置函数会将newValue 分配给此QAtomicPointer 并返回 true。如果值不相同,则此函数不执行任何操作,并返回false
。
该函数使用有序 memory ordering 语义,确保原子操作前后的内存访问(按程序顺序)不得重新排序。
bool QAtomicPointer::testAndSetRelaxed(T *expectedValue, T *newValue)
原子测试和设置。
如果此QAtomicPointer 的当前值是expectedValue ,则测试和设置函数会将newValue 分配给此QAtomicPointer 并返回 true。如果值不相同,则此函数不执行任何操作,并返回false
。
该函数使用宽松的 memory ordering 语义,让编译器和处理器自由地重新安排内存访问顺序。
bool QAtomicPointer::testAndSetRelease(T *expectedValue, T *newValue)
原子测试和设置。
如果此QAtomicPointer 的当前值是expectedValue ,则测试和设置函数会将newValue 分配给此QAtomicPointer 并返回 true。如果值不相同,则该函数不会执行任何操作,并返回false
。
该函数使用release memory ordering 语义,确保原子操作前的内存访问(按程序顺序)在原子操作后不得重新排序。
[noexcept]
QAtomicPointer<T> &QAtomicPointer::operator=(const QAtomicPointer<T> &other)
将other 赋值给QAtomicPointer ,并返回对QAtomicPointer 的引用。
宏文档
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
当只有某些处理器支持指针上的原子取加时,才会定义该宏。请使用QAtomicPointer::isFetchAndAddNative() 函数检查您的处理器支持哪些功能。
Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_WAIT_FREE
该宏与Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_ALWAYS_NATIVE 一起定义,用于表示指针上的原子取加是免等待的。
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
当只有某些处理器支持指针上的原子取存时,才会定义该宏。请使用QAtomicPointer::isFetchAndStoreNative() 函数检查您的处理器支持哪些功能。
Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_WAIT_FREE
该宏与Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_ALWAYS_NATIVE 一起定义,表示指针上的原子取存是免等待的。
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
当只有某些处理器支持指针的原子测试和设置时,才会定义该宏。请使用QAtomicPointer::isTestAndSetNative() 函数检查您的处理器支持哪些功能。
Q_ATOMIC_POINTER_TEST_AND_SET_IS_WAIT_FREE
该宏与Q_ATOMIC_POINTER_TEST_AND_SET_IS_ALWAYS_NATIVE 一起定义,表示指针上的原子测试和设置是免等待的。
© 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.