std::atomic

C++

语言

标准库头文件

自立与有宿主实现

具名要求

语言支持库

概念库 (C++20)

诊断库

工具库

字符串库

容器库

迭代器库

范围库 (C++20)

算法库

数值库

本地化库

输入/输出库

文件系统库 (C++17)

正则表达式库 (C++11)

原子操作库 (C++11)

线程支持库 (C++11)

技术规范

原子操作库

类

atomic(C++11)

atomic_ref(C++20)

函数

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_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(C++11)

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)

初始化

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

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

ATOMIC_FLAG_INIT(C++11)(C++20 中弃用)

内存顺序

memory_order(C++11)

kill_dependency(C++11)

atomic_thread_fence(C++11)

atomic_signal_fence(C++11)

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)

特化的成员函数

atomic::fetch_add

atomic::fetch_sub

atomic::fetch_and

atomic::fetch_or

atomic::fetch_xor

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

atomic::operator+=atomic::operator-=atomic::operator&=atomic::operator|=atomic::operator^=

定义于头文件

template< class T >

struct atomic;

(1)

(C++11 起)

template< class U >

struct atomic;

(2)

(C++11 起)

定义于头文件

template

struct atomic>;

(3)

(C++20 起)

template

struct atomic>;

(4)

(C++20 起)

每个 std::atomic 模板的实例化和全特化定义一个原子类型。若一个线程写入原子对象，同时另一线程从它读取，则行为良好定义（数据竞争的细节见内存模型）。

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

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

特化

初等模板

初等 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::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 ；

任何头文件 中的 typedef 所需的额外整数类型。

另外，结果的 std::atomic 特化拥有标准布局、平凡默认构造函数 (C++20 前)和平凡析构函数。定义有符号整数算术为使用补码；无未定义结果。

对浮点类型的特化

以浮点类型 float 、 double 和 long double 之一实例化时， std::atomic 提供适合于浮点类型的额外原子操作，例如 fetch_add 和 fetch_sub 。

另外，结果的 std::atomic 特化拥有标准布局和平凡析构函数。

无操作导致未定义行为，即使结果不能以浮点类型表示。有效的浮点环境可能不同于调用方线程的浮点环境。

(C++20 起)

类型别名

为 bool 和所有上面列出的整数类型提供如下类型别名：

类型别名

定义

std::atomic_bool

std::atomic

std::atomic_char

std::atomic

std::atomic_schar

std::atomic

std::atomic_uchar

std::atomic

std::atomic_short

std::atomic

std::atomic_ushort

std::atomic

std::atomic_int

std::atomic

std::atomic_uint

std::atomic

std::atomic_long

std::atomic

std::atomic_ulong

std::atomic

std::atomic_llong

std::atomic

std::atomic_ullong

std::atomic

std::atomic_char8_t (C++20)

std::atomic

std::atomic_char16_t

std::atomic

std::atomic_char32_t

std::atomic

std::atomic_wchar_t

std::atomic

std::atomic_int8_t

std::atomic

std::atomic_uint8_t

std::atomic

std::atomic_int16_t

std::atomic

std::atomic_uint16_t

std::atomic

std::atomic_int32_t

std::atomic

std::atomic_uint32_t

std::atomic

std::atomic_int64_t

std::atomic

std::atomic_uint64_t

std::atomic

std::atomic_int_least8_t

std::atomic

std::atomic_uint_least8_t

std::atomic

std::atomic_int_least16_t

std::atomic

std::atomic_uint_least16_t

std::atomic

std::atomic_int_least32_t

std::atomic

std::atomic_uint_least32_t

std::atomic

std::atomic_int_least64_t

std::atomic

std::atomic_uint_least64_t

std::atomic

std::atomic_int_fast8_t

std::atomic

std::atomic_uint_fast8_t

std::atomic

std::atomic_int_fast16_t

std::atomic

std::atomic_uint_fast16_t

std::atomic

std::atomic_int_fast32_t

std::atomic

std::atomic_uint_fast32_t

std::atomic

std::atomic_int_fast64_t

std::atomic

std::atomic_uint_fast64_t

std::atomic

std::atomic_intptr_t

std::atomic

std::atomic_uintptr_t

std::atomic

std::atomic_size_t

std::atomic

std::atomic_ptrdiff_t

std::atomic

std::atomic_intmax_t

std::atomic

std::atomic_uintmax_t

std::atomic

注意： std::atomic_intN_t 、 std::atomic_uintN_t 、 std::atomic_intptr_t 及 atomic_uintptr_t 分别若且唯若定义了 std::intN_t 、 std::uintN_t 、 std::intptr_t 及 std::uintptr_t 才有定义。

提供额外的特殊用途类型别名：

std::atomic_signed_lock_free

免锁且对于等待/提醒最高效的有符号整数原子类型

std::atomic_unsigned_lock_free

免锁且对于等待/提醒最高效的无符号整数原子类型

(C++20 起)

成员类型

成员类型

定义

value_type

T (无论是否特化)

difference_type

value_type (仅对 atomic 和 atomic (C++20 起) 特化) std::ptrdiff_t (仅对 atomic 特化)

difference_type 不在初等 atomic 模板中，或不在对 std::shared_ptr 和 std::weak_ptr 的部分特化中定义。

成员函数

(构造函数)

构造原子对象 (公开成员函数)

operator=

存储值于原子对象 (公开成员函数)

is_lock_free

检查原子对象是否免锁 (公开成员函数)

store

原子地以非原子对象替换原子对象的值 (公开成员函数)

load

原子地获得原子对象的值 (公开成员函数)

operator T

从原子对象加载值 (公开成员函数)

exchange

原子地替换原子对象的值并获得它先前持有的值 (公开成员函数)

compare_exchange_weakcompare_exchange_strong

原子地比较原子对象与非原子参数的值，若相等则进行交换，若不相等则进行加载 (公开成员函数)

wait(C++20)

阻塞线程直至被提醒且原子值更改 (公开成员函数)

notify_one(C++20)

提醒至少一个在原子对象上的等待中阻塞的线程 (公开成员函数)

notify_all(C++20)

提醒所有在原子对象上的等待中阻塞的线程 (公开成员函数)

常量

is_always_lock_free[静态] (C++17)

指示该类型是否始终免锁 (公开静态成员常量)

特化成员函数

fetch_add

原子地将参数加到存储于原子对象的值，并返回先前保有的值 (公开成员函数)

fetch_sub

原子地从存储于原子对象的值减去参数，并获得先前保有的值 (公开成员函数)

fetch_and

原子地进行参数和原子对象的值的逐位与，并获得先前保有的值 (公开成员函数)

fetch_or

原子地进行参数和原子对象的值的逐位或，并获得先前保有的值 (公开成员函数)

fetch_xor

原子地进行参数和原子对象的值的逐位异或，并获得先前保有的值 (公开成员函数)

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

令原子值增加或减少一 (公开成员函数)

operator+=operator-=operator&=operator|=operator^=

加、减，或与原子值进行逐位与、或、异或 (公开成员函数)

注解

存在等价于 std::atomic 所有成员函数的非成员函数模板。这些非成员函数可以额外对非 std::atomic 特化的类型重载，但不能保证原子性。标准库中仅有的这种类型是 std::shared_ptr 。

gcc 和 clang 上，此处描述的某些功能要求通过 -latomic 链接。

缺陷报告

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

DR

应用于

出版时的行为

正确行为

LWG 2441

C++11

添加了(可选)定宽整数类型的特化

P0558R1

C++11

实质上重写了规定以解决数个问题

LWG 3012

C++11

std::atomic 对任何可平凡复制但非可复制的 T 容许

禁止这种特化

参阅

atomic_flag(C++11)

免锁的布尔原子类型 (类)

std::atomic(C++20)

原子共享指针 (类模板特化)

std::atomic(C++20)

原子弱指针 (类模板特化)

引用

C++11 standard (ISO/IEC 14882:2011):

29.5 Atomic types [atomics.types.generic]