命名空间
变体
操作

std::atomic

来自 cppreference.com
< cpp‎ | atomic
 
 
并发支持库
线程
(C++11)
(C++20)
this_thread 命名空间
(C++11)
(C++11)
(C++11)
协作取消
互斥
(C++11)
通用锁管理
(C++11)
(C++11)
(C++11)
(C++11)
(C++11)
条件变量
(C++11)
信号量
闩锁和屏障
(C++20)
(C++20)
期货
(C++11)
(C++11)
(C++11)
(C++11)
安全回收
(C++26)
危险指针
原子类型
atomic
(C++11)
(C++20)
原子类型初始化
(C++11)(C++20 中已弃用)
(C++11)(C++20 中已弃用)
内存排序
用于原子操作的自由函数
用于原子标志的自由函数
 
 
定义在头文件 <atomic>
template< class T >
struct atomic;
(1) (自 C++11 起)
template< class U >
struct atomic<U*>;
(2) (自 C++11 起)
定义在头文件 <memory>
template< class U >
struct atomic<std::shared_ptr<U>>;
(3) (自 C++20 起)
template< class U >
struct atomic<std::weak_ptr<U>>;
(4) (自 C++20 起)
定义在头文件 <stdatomic.h>
#define _Atomic(T) /* see below */
(5) (自 C++23 起)

std::atomic 模板的每个实例化和完整特化都定义了一个原子类型。如果一个线程写入原子对象,而另一个线程从中读取,则行为是定义明确的(有关数据竞争的详细信息,请参阅 内存模型)。

此外,对原子对象的访问可能会建立线程间同步,并按照 std::memory_order 指定的顺序对非原子内存访问进行排序。

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

兼容性宏 _Atomic<stdatomic.h> 中提供,因此只要两者都格式正确,_Atomic(T) 就与 std::atomic<T> 相同。

当包含 <stdatomic.h> 时,命名空间 std 中的任何声明是否可用是未指定的。

(自 C++23 起)

内容

[编辑] 特化

[编辑] 主模板

std::atomic 模板可以用任何满足 TriviallyCopyable 类型的 T 实例化,该类型同时满足 CopyConstructibleCopyAssignable。如果以下任何值为 false,则程序格式错误。

struct Counters { int a; int b; }; // user-defined trivially-copyable type
std::atomic<Counters> cnt;         // specialization for the user-defined type

std::atomic<bool> 使用主模板。 它保证是一个 标准布局结构体 并且拥有一个 平凡析构函数.

[edit] 偏特化

标准库为以下类型提供了 std::atomic 模板的偏特化,它们拥有主模板不具备的额外属性

2) 针对所有指针类型的偏特化 std::atomic<U*>。 这些特化拥有标准布局,平凡默认构造函数,(直到 C++20) 和平凡析构函数。 除了为所有原子类型提供的操作外,这些特化还额外支持适合指针类型的原子算术运算,比如 fetch_addfetch_sub.
3,4) 针对 std::shared_ptrstd::weak_ptr 提供了偏特化 std::atomic<std::shared_ptr<U>>std::atomic<std::weak_ptr<U>>.

有关详情,请参见 std::atomic<std::shared_ptr>std::atomic<std::weak_ptr>.

(自 C++20 起)

[edit] 针对整数类型的特化

当使用以下整数类型之一实例化时,std::atomic 提供适合整数类型的额外原子操作,比如 fetch_addfetch_subfetch_andfetch_orfetch_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;
  • 头文件 <cstdint> 中的类型定义所需的任何其他整数类型。

此外,生成的 std::atomic<Integral> 特化拥有标准布局,平凡默认构造函数,(直到 C++20) 和平凡析构函数。 有符号整数算术被定义为使用二进制补码;没有未定义的结果。

针对浮点类型的特化

当使用 cv 无限定浮点类型(float, double, long double 和 cv 无限定 扩展浮点类型(自 C++23 起))之一实例化时,std::atomic 提供适合浮点类型的额外原子操作,比如 fetch_addfetch_sub.

此外,生成的 std::atomic<Floating> 特化拥有标准布局和平凡析构函数。

即使结果在浮点类型中不可表示,也不会产生未定义的行为。 生效的 浮点环境 可能与调用线程的浮点环境不同。

(自 C++20 起)

[edit] 成员类型

成员类型 定义
value_type T (无论是否特化)
difference_type value_type (仅针对 atomic<Integral> atomic<Floating>(自 C++20 起) 特化)
std::ptrdiff_t (仅针对 std::atomic<U*> 特化)

difference_type 在主 std::atomic 模板或针对 std::shared_ptrstd::weak_ptr 的偏特化中未定义。

[edit] 成员函数

构造一个原子对象
(公有成员函数) [edit]
将一个值存储到一个原子对象中
(公有成员函数) [edit]
检查原子对象是否为无锁
(公有成员函数) [edit]
原子地将原子对象的值替换为一个非原子参数
(公有成员函数) [edit]
原子地获取原子对象的值
(公有成员函数) [edit]
从原子对象中加载一个值
(公有成员函数) [edit]
原子地替换原子对象的值并获取先前保存的值
(公有成员函数) [edit]
原子地将原子对象的值与非原子参数进行比较,如果相等则执行原子交换,否则执行原子加载
(公有成员函数) [edit]
(C++20)
阻塞线程,直到收到通知并且原子值发生改变
(公有成员函数) [edit]
至少通知一个正在等待原子对象的线程
(公有成员函数) [edit]
通知所有正在等待原子对象的阻塞线程
(公有成员函数) [edit]

常量

[static] (C++17)
表示该类型始终为无锁
(公有静态成员常量) [edit]

[edit] 特化成员函数

针对整数、浮点(自 C++20 起) 和指针类型特化
原子地将参数添加到存储在原子对象中的值中,并获取先前保存的值
(公有成员函数) [edit]
原子地从存储在原子对象中的值中减去参数,并获取先前保存的值
(公有成员函数) [edit]
对原子值进行加或减
(公有成员函数) [edit]
仅针对整数和指针类型特化
(C++26)
原子地对参数和原子对象的值执行 std::max 操作,并获取先前保存的值
(公有成员函数) [edit]
(C++26)
原子地对参数和原子对象的值执行 std::min 操作,并获取先前保存的值
(公有成员函数) [edit]
将原子值加一或减一。
(公有成员函数) [编辑]
专门用于仅限整数类型
原子地对原子对象的值与参数进行按位与运算,并获取之前保存的值。
(公有成员函数) [编辑]
原子地对原子对象的值与参数进行按位或运算,并获取之前保存的值。
(公有成员函数) [编辑]
原子地对原子对象的值与参数进行按位异或运算,并获取之前保存的值。
(公有成员函数) [编辑]
对原子值进行按位与、或、异或运算。
(公有成员函数) [编辑]

[编辑] 类型别名

bool 和上面列出的所有整数类型提供了类型别名,如下所示。

所有 std::atomic<Integral> 的别名
atomic_bool
(C++11)
std::atomic<bool>
(typedef) [编辑]
atomic_char
(C++11)
std::atomic<char>
(typedef) [编辑]
atomic_schar
(C++11)
std::atomic<signed char>
(typedef) [编辑]
atomic_uchar
(C++11)
std::atomic<unsigned char>
(typedef) [编辑]
atomic_short
(C++11)
std::atomic<short>
(typedef) [编辑]
atomic_ushort
(C++11)
std::atomic<unsigned short>
(typedef) [编辑]
atomic_int
(C++11)
std::atomic<int>
(typedef) [编辑]
atomic_uint
(C++11)
std::atomic<unsigned int>
(typedef) [编辑]
atomic_long
(C++11)
std::atomic<long>
(typedef) [编辑]
atomic_ulong
(C++11)
std::atomic<unsigned long>
(typedef) [编辑]
atomic_llong
(C++11)
std::atomic<long long>
(typedef) [编辑]
atomic_ullong
(C++11)
std::atomic<unsigned long long>
(typedef) [编辑]
atomic_char8_t
(C++20)
std::atomic<char8_t>
(typedef) [编辑]
atomic_char16_t
(C++11)
std::atomic<char16_t>
(typedef) [编辑]
atomic_char32_t
(C++11)
std::atomic<char32_t>
(typedef) [编辑]
atomic_wchar_t
(C++11)
std::atomic<wchar_t>
(typedef) [编辑]
atomic_int8_t
(C++11)(可选)
std::atomic<std::int8_t>
(typedef) [编辑]
atomic_uint8_t
(C++11)(可选)
std::atomic<std::uint8_t>
(typedef) [编辑]
atomic_int16_t
(C++11)(可选)
std::atomic<std::int16_t>
(typedef) [编辑]
atomic_uint16_t
(C++11)(可选)
std::atomic<std::uint16_t>
(typedef) [编辑]
atomic_int32_t
(C++11)(可选)
std::atomic<std::int32_t>
(typedef) [编辑]
atomic_uint32_t
(C++11)(可选)
std::atomic<std::uint32_t>
(typedef) [编辑]
atomic_int64_t
(C++11)(可选)
std::atomic<std::int64_t>
(typedef) [编辑]
atomic_uint64_t
(C++11)(可选)
std::atomic<std::uint64_t>
(typedef) [编辑]
atomic_int_least8_t
(C++11)
std::atomic<std::int_least8_t>
(typedef) [编辑]
atomic_uint_least8_t
(C++11)
std::atomic<std::uint_least8_t>
(typedef) [编辑]
atomic_int_least16_t
(C++11)
std::atomic<std::int_least16_t>
(typedef) [编辑]
atomic_uint_least16_t
(C++11)
std::atomic<std::uint_least16_t>
(typedef) [编辑]
atomic_int_least32_t
(C++11)
std::atomic<std::int_least32_t>
(typedef) [编辑]
atomic_uint_least32_t
(C++11)
std::atomic<std::uint_least32_t>
(typedef) [编辑]
atomic_int_least64_t
(C++11)
std::atomic<std::int_least64_t>
(typedef) [编辑]
atomic_uint_least64_t
(C++11)
std::atomic<std::uint_least64_t>
(typedef) [编辑]
atomic_int_fast8_t
(C++11)
std::atomic<std::int_fast8_t>
(typedef) [编辑]
atomic_uint_fast8_t
(C++11)
std::atomic<std::uint_fast8_t>
(typedef) [编辑]
atomic_int_fast16_t
(C++11)
std::atomic<std::int_fast16_t>
(typedef) [编辑]
atomic_uint_fast16_t
(C++11)
std::atomic<std::uint_fast16_t>
(typedef) [编辑]
atomic_int_fast32_t
(C++11)
std::atomic<std::int_fast32_t>
(typedef) [编辑]
atomic_uint_fast32_t
(C++11)
std::atomic<std::uint_fast32_t>
(typedef) [编辑]
atomic_int_fast64_t
(C++11)
std::atomic<std::int_fast64_t>
(typedef) [编辑]
atomic_uint_fast64_t
(C++11)
std::atomic<std::uint_fast64_t>
(typedef) [编辑]
atomic_intptr_t
(C++11)(可选)
std::atomic<std::intptr_t>
(typedef) [编辑]
atomic_uintptr_t
(C++11)(可选)
std::atomic<std::uintptr_t>
(typedef) [编辑]
atomic_size_t
(C++11)
std::atomic<std::size_t>
(typedef) [编辑]
atomic_ptrdiff_t
(C++11)
std::atomic<std::ptrdiff_t>
(typedef) [编辑]
atomic_intmax_t
(C++11)
std::atomic<std::intmax_t>
(typedef) [编辑]
atomic_uintmax_t
(C++11)
std::atomic<std::uintmax_t>
(typedef) [编辑]
特殊类型别名
atomic_signed_lock_free
(C++20)
一种无锁的带符号整数原子类型,它对等待/通知操作的效率最高。
(typedef) [编辑]
atomic_unsigned_lock_free
(C++20)
一种无锁的无符号整数原子类型,它对等待/通知操作的效率最高。
(typedef) [编辑]
注意: std::atomic_intN_t, std::atomic_uintN_t, std::atomic_intptr_tstd::atomic_uintptr_t 的定义与 std::intN_t, std::uintN_t, std::intptr_tstd::uintptr_t 的定义相同。

在独立实现中,std::atomic_signed_lock_freestd::atomic_unsigned_lock_free 是可选的。

(自 C++20 起)

[编辑] 注释

std::atomic 的所有成员函数都有相应的非成员函数模板等价物。这些非成员函数可能还会为不是 std::atomic 的专门化类型重载,但能够保证原子性。标准库中唯一的此类类型是 std::shared_ptr<U>

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

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

在 gcc 和 clang 上,此处描述的一些功能需要链接 -latomic

[编辑] 示例

#include <atomic>
#include <iostream>
#include <thread>
#include <vector>
 
std::atomic_int acnt;
int cnt;
 
void f()
{
    for (int n = 0; n < 10000; ++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<std::jthread> 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++ 标准。

DR 应用于 已发布的行为 正确行为
LWG 2441 C++11 可选类型的原子版本的类型定义
固定宽度整数类型 丢失了
已添加
LWG 3012 C++11 std::atomic<T> 允许用于任何 T
它可以平凡地复制,但不可复制
禁止此类特化
LWG 3949 C++17 要求 std::atomic<bool> 具有
平凡的析构函数在 C++17 中意外被删除
添加回来
P0558R1 C++11 某些
原子类型函数的模板参数推导可能会意外
失败; 提供了无效的指针操作
规范已彻底重写
成员类型定义 value_type
difference_type 已添加

[编辑] 另请参阅

无锁布尔原子类型
(类) [编辑]
原子共享指针
(类模板特化) [编辑]
原子弱指针
(类模板特化) [编辑]
C 文档 针对 原子类型