std::atomic

C++

编译器支持

自由（freestanding）与宿主（hosted）

语言

标准库

标准库头文件

具名要求

特性测试宏 (C++20)

语言支持库

概念库 (C++20)

诊断库

内存管理库

元编程库 (C++11)

通用工具库

容器库

迭代器库

范围库 (C++20)

算法库

字符串库

文本处理库

数值库

日期和时间库

输入/输出库

文件系统库 (C++17)

并发支持库 (C++11)

执行控制库 (C++26)

技术规范

符号索引

外部库

[编辑] 并发支持库

线程

thread(C++11)

jthread(C++20)

hardware_destructive_interference_sizehardware_constructive_interference_size(C++17)(C++17)

this_thread 命名空间

get_id(C++11)

yield(C++11)

sleep_for(C++11)

sleep_until(C++11)

协同取消

stop_token(C++20)

inplace_stop_token(C++26)

never_stop_token(C++26)

stop_source(C++20)

inplace_stop_source(C++26)

stop_callback(C++20)

inplace_stop_callback(C++26)

stop_callback_for_t(C++26)

stoppable_token(C++26)

unstoppable_token(C++26)

stoppable-source(C++26)

stoppable-callback-for(C++26)

互斥

mutex(C++11)

recursive_mutex(C++11)

shared_mutex(C++17)

timed_mutex(C++11)

recursive_timed_mutex(C++11)

shared_timed_mutex(C++14)

通用锁管理

lock(C++11)

lock_guard(C++11)

scoped_lock(C++17)

unique_lock(C++11)

shared_lock(C++14)

once_flag(C++11)

call_once(C++11)

try_lock(C++11)

defer_locktry_to_lockadopt_lockdefer_lock_ttry_to_lock_tadopt_lock_t(C++11)(C++11)(C++11)(C++11)(C++11)(C++11)

条件变量

condition_variable(C++11)

condition_variable_any(C++11)

notify_all_at_thread_exit(C++11)

cv_status(C++11)

信号量

counting_semaphorebinary_semaphore(C++20)(C++20)

门闩和屏障

latch(C++20)

barrier(C++20)

期值

promise(C++11)

future(C++11)

shared_future(C++11)

packaged_task(C++11)

async(C++11)

launch(C++11)

future_status(C++11)

future_error(C++11)

future_category(C++11)

future_errc(C++11)

安全回收

rcu_obj_base(C++26)

rcu_domain(C++26)

rcu_default_domain(C++26)

rcu_synchronize(C++26)

rcu_barrier(C++26)

rcu_retire(C++26)

危险指针

hazard_pointer_obj_base(C++26)

hazard_pointer(C++26)

make_hazard_pointer(C++26)

原子类型

atomic(C++11)

atomic_ref(C++20)

atomic_flag(C++11)

原子类型的初始化

atomic_init(C++11)(C++20 中已弃用)

ATOMIC_VAR_INIT(C++11)(C++20 中已弃用)

ATOMIC_FLAG_INIT(C++11)

内存排序

memory_order(C++11)

kill_dependency(C++11)(C++26 中已弃用)

atomic_thread_fence(C++11)

atomic_signal_fence(C++11)

原子操作的自由函数

atomic_storeatomic_store_explicit(C++11)(C++11)

atomic_loadatomic_load_explicit(C++11)(C++11)

atomic_exchangeatomic_exchange_explicit(C++11)(C++11)

atomic_compare_exchange_weakatomic_compare_exchange_weak_explicitatomic_compare_exchange_strongatomic_compare_exchange_strong_explicit(C++11)(C++11)(C++11)(C++11)

atomic_fetch_addatomic_fetch_add_explicit(C++11)(C++11)

atomic_fetch_subatomic_fetch_sub_explicit(C++11)(C++11)

atomic_fetch_andatomic_fetch_and_explicit(C++11)(C++11)

atomic_fetch_oratomic_fetch_or_explicit(C++11)(C++11)

atomic_fetch_xoratomic_fetch_xor_explicit(C++11)(C++11)

atomic_fetch_maxatomic_fetch_max_explicit(C++26)(C++26)

atomic_fetch_minatomic_fetch_min_explicit(C++26)(C++26)

atomic_is_lock_free(C++11)

atomic_waitatomic_wait_explicit(C++20)(C++20)

atomic_notify_one(C++20)

atomic_notify_all(C++20)

原子标志的自由函数

atomic_flag_test_and_setatomic_flag_test_and_set_explicit(C++11)(C++11)

atomic_flag_clearatomic_flag_clear_explicit(C++11)(C++11)

atomic_flag_testatomic_flag_test_explicit(C++20)(C++20)

atomic_flag_waitatomic_flag_wait_explicit(C++20)(C++20)

atomic_flag_notify_one(C++20)

atomic_flag_notify_all(C++20)

[编辑] std::atomic

成员函数

atomic::atomic

atomic::operator=

atomic::is_lock_free

atomic::store

atomic::load

atomic::operator T

atomic::exchange

atomic::compare_exchange_strongatomic::compare_exchange_weak

atomic::wait(C++20)

atomic::notify_one(C++20)

atomic::notify_all(C++20)

常量

atomic::is_always_lock_free(C++17)

Specialized member functions

Specialized for integral,floating-point (C++20)and pointer types

atomic::fetch_add

atomic::fetch_sub

atomic::operator+=atomic::operator-=

Specialized for integral andpointer types only

atomic::fetch_max(C++26)

atomic::fetch_min(C++26)

atomic::operator++atomic::operator++(int)atomic::operator--atomic::operator--(int)

Specialized for integral types only

atomic::fetch_and

atomic::fetch_or

atomic::fetch_xor

atomic::operator&=atomic::operator|=atomic::operator^=

[编辑]

定义于头文件

template< class T >

struct atomic;

(1)

(C++11 起)

template< class U >

struct atomic;

(2)

(C++11 起)

定义于头文件

template< class U >

struct atomic>;

(3)

(C++20 起)

template< class U >

struct atomic>;

(4)

(C++20 起)

Defined in header

#define _Atomic(T) /* 见下文 */

(5)

(C++23 起)

std::atomic 模板的每个实例化和完全特化都定义了一个原子类型。如果一个线程写入一个原子对象，而另一个线程从它读取，则行为是定义良好的（有关数据竞争的详细信息，请参见内存模型）。

此外，对原子对象的访问可以建立线程间同步并按 std::memory_order 指定的顺序访问非原子内存。

std::atomic 既不可复制也不可移动。

在 中提供了兼容宏 _Atomic，使得 _Atomic(T) 与 std::atomic 相同，同时两者都是良好形成的。

当包含 时，命名空间 std 中的任何声明是否可用是未指定的。

(C++23 起)

目录

1 特化

1.1 主模板

1.2 部分特化

1.3 整数类型的特化

1.4 浮点类型的特化

2 成员类型

3 成员函数

4 常量

5 专用成员函数

5.1 针对整数、浮点(C++20 起)和指针类型特化

5.2 仅针对整数和指针类型特化

5.3 仅针对整数类型特化

6 类型别名

6.1 所有 std::atomic 的别名

6.2 特殊用途类型的别名

7 注释

8 示例

9 缺陷报告

10 参阅

[编辑] 特化

[编辑] 主模板

主 std::atomic 模板可以使用任何满足 CopyConstructible 和 CopyAssignable 的 可简单复制 (TriviallyCopyable) 类型 T 进行实例化。如果以下任何值为 false，则程序是非良构的

std::is_trivially_copyable::value

std::is_copy_constructible::value

std::is_move_constructible::value

std::is_copy_assignable::value

std::is_move_assignable::value

std::is_same::type>::value

struct Counters { int a; int b; }; // user-defined trivially-copyable type

std::atomic cnt; // specialization for the user-defined type

std::atomic 使用主模板。它保证是一个标准布局结构并具有平凡析构函数。

[编辑] 部分特化

标准库为以下类型的 std::atomic 模板提供了部分特化，这些类型具有主模板不具备的额外属性

2) 针对所有指针类型的部分特化 std::atomic。这些特化具有标准布局、平凡默认构造函数，(C++20 前)和平凡析构函数。除了为所有原子类型提供的操作之外，这些特化还额外支持适用于指针类型的原子算术操作，例如 fetch_add、fetch_sub。

3,4) 为 std::shared_ptr 和 std::weak_ptr 提供了部分特化 std::atomic> 和 std::atomic>。

详见 std::atomic 和 std::atomic。

(C++20 起)

[编辑] 整数类型的特化

当实例化为以下整数类型之一时，std::atomic 提供了适用于整数类型的额外原子操作，例如 fetch_add、fetch_sub、fetch_and、fetch_or、fetch_xor

字符类型 char、char8_t(C++20 起)、char16_t、char32_t 和 wchar_t；标准有符号整数类型：signed char、short、int、long 和 long long；标准无符号整数类型：unsigned char、unsigned short、unsigned int、unsigned long 和 unsigned long long；头文件 中的 typedefs 所需的任何其他整数类型。

此外，由此产生的 std::atomic 特化具有标准布局、平凡默认构造函数，(C++20 前)和平凡析构函数。有符号整数算术定义为使用二进制补码；没有未定义的结果。

浮点类型的特化

当实例化为无 cv 限定的浮点类型（float、double、long double 以及无 cv 限定的扩展浮点类型(C++23 起)）时，std::atomic 提供了适用于浮点类型的额外原子操作，例如 fetch_add 和 fetch_sub。

此外，由此产生的 std::atomic 特化具有标准布局和平凡析构函数。

即使结果无法在浮点类型中表示，也没有操作会导致未定义行为。浮点环境可能与调用线程的浮点环境不同。

(C++20 起)

[编辑] 成员类型

类型

定义

value_type

T (无论是否特化)

difference_type[1]

value_type (仅适用于 atomic 和 atomic(C++20 起) 特化)

std::ptrdiff_t (仅适用于 std::atomic 特化)

↑ difference_type 未在主 std::atomic 模板或 std::shared_ptr 和 std::weak_ptr 的部分特化中定义。

[编辑] 成员函数

(构造函数)

constructs an atomic object (public member function) [编辑]

operator=

stores a value into an atomic object (public member function) [编辑]

is_lock_free

检查原子对象是否为无锁 (public member function) [编辑]

store

原子地将原子对象的值替换为非原子参数 (public member function) [编辑]

load

atomically obtains the value of the atomic object (public member function) [编辑]

operator T

loads a value from an atomic object (public member function) [编辑]

exchange

atomically replaces the value of the atomic object and obtains the value held previously (public member function) [编辑]

compare_exchange_weakcompare_exchange_strong

原子地将原子对象的值与非原子参数进行比较，如果相等则执行原子交换，否则执行原子加载 (public member function) [编辑]

wait(C++20)

阻塞线程直到被通知且原子值改变 (public member function) [编辑]

notify_one(C++20)

通知至少一个等待原子对象的线程 (public member function) [编辑]

notify_all(C++20)

通知所有被原子对象阻塞的线程 (public member function) [编辑]

常量

is_always_lock_free[static] (C++17)

指示该类型始终是无锁的 (public static member constant) [编辑]

[编辑] 专用成员函数

针对整数、浮点(C++20 起)和指针类型特化

fetch_add

原子地将参数添加到原子对象中存储的值，并获取之前持有的值 (public member function) [编辑]

fetch_sub

原子地从原子对象中存储的值中减去参数，并获取之前持有的值 (public member function) [编辑]

operator+=operator-=

对原子值进行加减 (public member function) [编辑]

仅针对整数和指针类型特化

fetch_max(C++26)

原子地在参数和原子对象的值之间执行 std::max，并获取之前持有的值 (public member function) [编辑]

fetch_min(C++26)

原子地在参数和原子对象的值之间执行 std::min，并获取之前持有的值 (public member function) [编辑]

operator++operator++(int)operator--operator--(int)

将原子值递增或递减一 (public member function) [编辑]

Specialized for integral types only

fetch_and

原子地在参数和原子对象的值之间执行按位与运算，并获取之前持有的值 (public member function) [编辑]

fetch_or

原子地在参数和原子对象的值之间执行按位或运算，并获取之前持有的值 (public member function) [编辑]

fetch_xor

原子地在参数和原子对象的值之间执行按位异或运算，并获取之前持有的值 (public member function) [编辑]

operator&=operator|=operator^=

对原子值执行按位与、或、异或运算 (public member function) [编辑]

[编辑] 类型别名

为 bool 和所有上述整数类型提供了类型别名，如下所示

所有 std::atomic 的别名

atomic_bool(C++11)

std::atomic (typedef) [编辑]

atomic_char(C++11)

std::atomic (typedef) [编辑]

atomic_schar(C++11)

std::atomic (typedef) [编辑]

atomic_uchar(C++11)

std::atomic (typedef) [编辑]

atomic_short(C++11)

std::atomic (typedef) [编辑]

atomic_ushort(C++11)

std::atomic (typedef) [编辑]

atomic_int(C++11)

std::atomic (typedef) [编辑]

atomic_uint(C++11)

std::atomic (typedef) [编辑]

atomic_long(C++11)

std::atomic (typedef) [编辑]

atomic_ulong(C++11)

std::atomic (typedef) [编辑]

atomic_llong(C++11)

std::atomic (typedef) [编辑]

atomic_ullong(C++11)

std::atomic (typedef) [编辑]

atomic_char8_t(C++20)

std::atomic (typedef) [编辑]

atomic_char16_t(C++11)

std::atomic (typedef) [编辑]

atomic_char32_t(C++11)

std::atomic (typedef) [编辑]

atomic_wchar_t(C++11)

std::atomic (typedef) [编辑]

atomic_int8_t(C++11)(可选)

std::atomic (typedef) [编辑]

atomic_uint8_t(C++11)(可选)

std::atomic (typedef) [编辑]

atomic_int16_t(C++11)(可选)

std::atomic (typedef) [编辑]

atomic_uint16_t(C++11)(可选)

std::atomic (typedef) [编辑]

atomic_int32_t(C++11)(可选)

std::atomic (typedef) [编辑]

atomic_uint32_t(C++11)(可选)

std::atomic (typedef) [编辑]

atomic_int64_t(C++11)(可选)

std::atomic (typedef) [编辑]

atomic_uint64_t(C++11)(可选)

std::atomic (typedef) [编辑]

atomic_int_least8_t(C++11)

std::atomic (typedef) [编辑]

atomic_uint_least8_t(C++11)

std::atomic (typedef) [编辑]

atomic_int_least16_t(C++11)

std::atomic (typedef) [编辑]

atomic_uint_least16_t(C++11)

std::atomic (typedef) [编辑]

atomic_int_least32_t(C++11)

std::atomic (typedef) [编辑]

atomic_uint_least32_t(C++11)

std::atomic (typedef) [编辑]

atomic_int_least64_t(C++11)

std::atomic (typedef) [编辑]

atomic_uint_least64_t(C++11)

std::atomic (typedef) [编辑]

atomic_int_fast8_t(C++11)

std::atomic (typedef) [编辑]

atomic_uint_fast8_t(C++11)

std::atomic (typedef) [编辑]

atomic_int_fast16_t(C++11)

std::atomic (typedef) [编辑]

atomic_uint_fast16_t(C++11)

std::atomic (typedef) [编辑]

atomic_int_fast32_t(C++11)

std::atomic (typedef) [编辑]

atomic_uint_fast32_t(C++11)

std::atomic (typedef) [编辑]

atomic_int_fast64_t(C++11)

std::atomic (typedef) [编辑]

atomic_uint_fast64_t(C++11)

std::atomic (typedef) [编辑]

atomic_intptr_t(C++11)(可选)

std::atomic (typedef) [编辑]

atomic_uintptr_t(C++11)(可选)

std::atomic (typedef) [编辑]

atomic_size_t(C++11)

std::atomic (typedef) [编辑]

atomic_ptrdiff_t(C++11)

std::atomic (typedef) [编辑]

atomic_intmax_t(C++11)

std::atomic (typedef) [编辑]

atomic_uintmax_t(C++11)

std::atomic (typedef) [编辑]

特殊用途类型的别名

atomic_signed_lock_free(C++20)

一个无锁且等待/通知效率最高的有符号整型原子类型 (typedef) [编辑]

atomic_unsigned_lock_free(C++20)

一个无锁且等待/通知效率最高的无符号整型原子类型 (typedef) [编辑]

注意：当且仅当定义了 std::intN_t、std::uintN_t、std::intptr_t 和 std::uintptr_t 时，才定义 std::atomic_intN_t、std::atomic_uintN_t、std::atomic_intptr_t 和 std::atomic_uintptr_t。

std::atomic_signed_lock_free 和 std::atomic_unsigned_lock_free 在独立实现中是可选的。

(C++20 起)

[编辑] 注意

std::atomic 的所有成员函数都有非成员函数模板等效项。这些非成员函数可以额外重载用于非 std::atomic 特化但能保证原子性的类型。标准库中唯一的此类类型是 std::shared_ptr。

_Atomic 是一个 关键字，用于在 C 中提供 原子类型。

建议实现确保 C 中 _Atomic(T) 的表示形式与 C++ 中 std::atomic 的表示形式对于每种可能的类型 T 都是相同的。用于确保原子性和内存顺序的机制应兼容。

在 GCC 和 Clang 上，这里描述的一些功能需要链接 -latomic。

特性测试宏

值

标准

特性

__cpp_lib_atomic_ref

201806L

(C++20)

std::atomic_ref

__cpp_lib_constexpr_atomic

202411L

(C++26)

constexpr std::atomic 和 std::atomic_ref

[编辑] 示例

运行此代码

#include

#include

#include

#include

std::atomic_int acnt;

int cnt;

void f()

{

for (auto n{10000}; n; --n)

{

++acnt;

++cnt;

// Note: for this example, relaxed memory order is sufficient,

// e.g. acnt.fetch_add(1, std::memory_order_relaxed);

}

}

int main()

{

{

std::vector pool;

for (int n = 0; n < 10; ++n)

pool.emplace_back(f);

}

std::cout << "The atomic counter is " << acnt << '\n'

<< "The non-atomic counter is " << cnt << '\n';

}

可能的输出

The atomic counter is 100000

The non-atomic counter is 69696

[编辑] 缺陷报告

下列更改行为的缺陷报告追溯地应用于以前出版的 C++ 标准。

缺陷报告

应用于

发布时的行为

正确的行为

LWG 2441

C++11

可选的原子版本的 typedef固定宽度整型 缺失

已添加

LWG 3012

C++11

std::atomic 允许用于任何可平凡复制但不可复制的 T

此类特化被禁止

LWG 3949

C++17

要求 std::atomic 具有平凡析构函数的措辞在 C++17 中意外删除

已添加回来

LWG 4069(P3323R1)

C++11

对 cv 限定 T 的支持存在疑问

禁止 T 为 cv 限定

P0558R1

C++11

一些函数模板参数推导对于原子类型可能会意外失败；提供了无效的指针操作

规范被大幅重写添加了成员 typedef value_type和 difference_type

[编辑] 另请参阅

atomic_flag(C++11)

无锁布尔原子类型 (类) [编辑]

std::atomic(C++20)

原子共享指针 (类模板特化) [编辑]

std::atomic(C++20)

原子弱指针 (类模板特化) [编辑]

C 文档 关于 原子类型