QAtomicPointer 类

template <typename T> class QAtomicPointer

The QAtomicPointer class is a template class that provides platform-independent atomic operations on pointers. 更多...

头文件 #include <QAtomicPointer>
CMakefind_package(Qt6 REQUIRED COMPONENTS Core)
target_link_libraries(mytarget PRIVATE Qt6::Core)
qmakeQT += core

公共函数

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
voidstoreRelaxed(T *newValue)
voidstoreRelease(T *newValue)
booltestAndSetAcquire(T *expectedValue, T *newValue)
booltestAndSetOrdered(T *expectedValue, T *newValue)
booltestAndSetRelaxed(T *expectedValue, T *newValue)
booltestAndSetRelease(T *expectedValue, T *newValue)
QAtomicPointer<T> &operator=(const QAtomicPointer<T> &other)

静态公共成员

详细描述

有关整数上的原子操作,请参阅QAtomicInteger类。

原子操作是一种复杂操作,可以无需中断完成。QAtomicPointer类提供了对指针的原子测试并设置、获取并存储以及获取并加的操作。

原子API

内存排序

QAtomicPointer提供了原子测试并设置、获取并存储和获取并加函数的多个实现。每个实现都定义了一个内存排序语义,该语义描述了处理器如何执行围绕原子指令的内存访问。由于许多现代架构允许乱序执行和内存排序,因此使用正确的语义是必要的,以确保应用程序在所有处理器上都能正常运行。

  • 宽松 - 内存排序不可指定,编译器和处理器可以自由重排序内存访问。
  • 获取 - 原子操作(在程序顺序)后的内存访问不能在原子操作之前重排序。
  • 释放 - 原子操作(在程序顺序)之前的内存访问不能在原子操作之后重排序。
  • 有序 - 结合了获取和释放语义。

测试并设置

如果QAtomicPointer的当前值是预期的值,则测试并设置函数将新值赋给QAtomicPointer并返回true。如果值不相同,则这些函数不做任何事情并返回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而努力,这个API能在所有处理器上运行是具有挑战性的。QAtomicPointer提供的API保证在所有处理器上以原子方式工作。然而,由于并非所有处理器都实现对QAtomicPointer提供的每个操作的支持,因此有必要公开处理器的信息。

您可以使用各种宏来在编译时检查您的硬件支持哪些特性。这些宏将告诉您硬件始终、有时或不支持特定操作。宏的格式为 Q_ATOMIC_POINTER_OPERATION_IS_HOW_NATIVE。 OPERATIONTEST_AND_SETFETCH_AND_STOREFETCH_AND_ADD 之一,而 HOW 是 ALWAYS、SOMETIMES 或 NOT 之一。对于每个操作,将始终Exactly 定义一个宏。例如,如果 Q_ATOMIC_POINTER_TEST_AND_SET_IS��

完成在常数时间内的是 wait-free 操作。此类操作不使用锁定或任何类型的循环实现。对于始终受支持的原子操作,并且是 wait-free 的,Qt 除定义 Q_ATOMIC_POINTER_OPERATION_IS_ALWAYS_NATIVE 之外,还定义了 Q_ATOMIC_POINTER_OPERATION_IS_WAIT_FREE。

在某些原子操作仅在处理器的较新一代中受支持的情况下,QAtomicPointer 还提供了使用 isTestAndSetNative()、isFetchAndStoreNative() 和 isFetchAndAddNative() 函数在运行时检查您的硬件支持的 typeof。使用 isTestAndSetWaitFree()、isFetchAndStoreWaitFree() 和 isFetchAndAddWaitFree() 函数可以检测 wait-free 实现。

以下是 QAtomicPointer 所有特性宏的完整列表

另请参阅 QAtomicIntegerqYieldCpu

成员函数说明

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

使用给定的 value 构造 QAtomicPointer。

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

构造另一个 other 的副本。

T *QAtomicPointer::fetchAndAddAcquire(qptrdiff valueToAdd)

原子 fetch-and-add。

读取此 QAtomicPointer 的当前值,然后在当前值上添加 valueToAdd,返回原始值。

此函数使用 acquire 内存排序 语义,这确保了在原子操作之后的内存访问(程序顺序)不会被重新排序。

T *QAtomicPointer::fetchAndAddOrdered(qptrdiff valueToAdd)

原子 fetch-and-add。

读取此 QAtomicPointer 的当前值,然后在当前值上添加 valueToAdd,返回原始值。

此函数使用 ordered 内存排序 语义,这确保了在原子操作之前和之后的内存访问(程序顺序)不允许重新排序。

T *QAtomicPointer::fetchAndAddRelaxed(qptrdiff valueToAdd)

原子 fetch-and-add。

读取此 QAtomicPointer 的当前值,然后在当前值上添加 valueToAdd,返回原始值。

此函数使用 relaxed 内存排序 语义,将内存访问的重新排序交由编译器和处理器自由处理。

T *QAtomicPointer::fetchAndAddRelease(qptrdiff valueToAdd)

原子 fetch-and-add。

读取此 QAtomicPointer 的当前值,然后在当前值上添加 valueToAdd,返回原始值。

此函数使用 release 输出 内存排序 语意,确保原子操作(根据程序顺序)之前的内存访问不可能在原子操作之后被重排。

T *QAtomicPointer::fetchAndStoreAcquire(T *newValue)

原子性加载和存储。

读取当前此 QAtomicPointer 的值,并将其分配给 newValue,返回原始值。

此函数使用 acquire 内存排序 语义,这确保了在原子操作之后的内存访问(程序顺序)不会被重新排序。

T *QAtomicPointer::fetchAndStoreOrdered(T *newValue)

原子性加载和存储。

读取当前此 QAtomicPointer 的值,并将其分配给 newValue,返回原始值。

此函数使用 ordered 内存排序 语义,这确保了在原子操作之前和之后的内存访问(程序顺序)不允许重新排序。

T *QAtomicPointer::fetchAndStoreRelaxed(T *newValue)

原子性加载和存储。

读取当前此 QAtomicPointer 的值,并将其分配给 newValue,返回原始值。

此函数使用 relaxed 内存排序 语义,将内存访问的重新排序交由编译器和处理器自由处理。

T *QAtomicPointer::fetchAndStoreRelease(T *newValue)

原子性加载和存储。

读取当前此 QAtomicPointer 的值,并将其分配给 newValue,返回原始值。

此函数使用 release 输出 内存排序 语意,确保原子操作(根据程序顺序)之前的内存访问不可能在原子操作之后被重排。

[静态常量] bool QAtomicPointer::isFetchAndAddNative()

如果使用原子处理器指令实现加载和加,则返回 true,否则返回 false

[静态常量] bool QAtomicPointer::isFetchAndAddWaitFree()

如果原子的加载和加是无阻塞的,则返回 true,否则返回 false

[静态常量] bool QAtomicPointer::isFetchAndStoreNative()

如果使用原子处理器指令实现加载和存储,则返回 true,否则返回 false

[静态常量] bool QAtomicPointer::isFetchAndStoreWaitFree()

如果原子的加载和存储是无阻塞的,则返回 true,否则返回 false

[静态常量] bool QAtomicPointer::isTestAndSetNative()

如果测试并设置是使用原子处理器指令实现的,则返回 true,否则返回 false

[静态常量] bool QAtomicPointer::isTestAndSetWaitFree()

如果原子的测试并设置是无阻塞的,则返回 true,否则返回 false

T *QAtomicPointer::loadAcquire() const

使用 "Acquire" 内存排序原子性地加载此 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)

原子测试并设置。

如果当前值是此QAtomicPointerexpectedValue,则测试并设置函数将newValue赋值给此QAtomicPointer并返回true。如果值不相同,此函数不执行任何操作,并返回:false

此函数使用 acquire 内存排序 语义,这确保了在原子操作之后的内存访问(程序顺序)不会被重新排序。

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

原子测试并设置。

如果当前值是此QAtomicPointerexpectedValue,则测试并设置函数将newValue赋值给此QAtomicPointer并返回true。如果值不相同,此函数不执行任何操作,并返回:false

此函数使用 ordered 内存排序 语义,这确保了在原子操作之前和之后的内存访问(程序顺序)不允许重新排序。

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

原子测试并设置。

如果当前值是此QAtomicPointerexpectedValue,则测试并设置函数将newValue赋值给此QAtomicPointer并返回true。如果值不相同,此函数不执行任何操作,并返回:false

此函数使用 relaxed 内存排序 语义,将内存访问的重新排序交由编译器和处理器自由处理。

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

原子测试并设置。

如果当前值是此QAtomicPointerexpectedValue,则测试并设置函数将newValue赋值给此QAtomicPointer并返回true。如果值不相同,此函数不执行任何操作,并返回:false

此函数使用 release 输出 内存排序 语意,确保原子操作(根据程序顺序)之前的内存访问不可能在原子操作之后被重排。

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

other赋值给此QAtomicPointer并返回对此QAtomicPointer的引用。

宏文档

Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_ALWAYS_NATIVE

如果您的处理器支持指针原子fetch-and-add,则定义此宏。

Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_NOT_NATIVE

当硬件不支持指针原子fetch-and-add时,定义此宏。

Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_SOMETIMES_NATIVE

当只有某些处理器代的处理器支持指针原子fetch-and-add时,定义此宏。使用QAtomicPointer::isFetchAndAddNative()函数来检查您的处理器支持什么。

Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_WAIT_FREE

定义此宏与Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_ALWAYS_NATIVE一起,表示指针的原子fetch-and-add是等待自由的。

Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_ALWAYS_NATIVE

如果您的处理器支持指针原子fetch-and-store,则定义此宏。

Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_NOT_NATIVE

当硬件不支持指针原子fetch-and-store时,定义此宏。

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.AtomicPointer.TestAndSet.IsWaitFree

此宏与Q_ATOMIC_POINTER_TEST_AND_SET_IS_ALWAYS_NATIVE共同定义,以指示指针上的原子测试-设置是等待自由的。

© 2024 Qt 公司有限公司。此处包含的文档贡献是各自所有者的版权。此处提供的文档服从根据自由软件基金会发布的GNU自由文档许可1.3版的条款。Qt及其相应标志是芬兰及其他在世界范围内注册的商标。所有其他商标均为其各自所有者的财产。