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^=

 

<tbody> </tbody>

ヘッダ <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以上)

std::atomic テンプレートの各実体化および完全特殊化はアトミック型を定義します。 あるスレッドがアトミックオブジェクトに書き込んでいる間に他のスレッドがそれを読み込んだ場合、その動作は well-defined です (データ競合の詳細はメモリモデルを参照してください)。

さらに、アトミックオブジェクトへのアクセスはスレッド間の同期を確立し、 std::memory_order によって指定された非アトミックメモリアクセスを順序付けることができます。

std::atomic はコピー可能でもムーブ可能でもありません。

特殊化

プライマリテンプレート

std::atomic のプライマリテンプレートは、 CopyConstructible と CopyAssignable の両方を満たす任意の TriviallyCopyable な型 T に対して実体化できます。 以下の値のいずれかが false の場合、プログラムは ill-formed です。

• std::is_trivially_copyable<T>::value
• std::is_copy_constructible<T>::value
• std::is_move_constructible<T>::value
• std::is_copy_assignable<T>::value
• std::is_move_assignable<T>::value

struct Counters { int a; int b; }; // ユーザ定義のトリビアルにコピー可能な型
std::atomic<Counters> cnt;         // そのユーザ定義型に対する特殊化

std::atomic<bool> はプライマリテンプレートを使用します。 これは標準レイアウト構造体であることが保証されます。

部分特殊化

標準ライブラリは以下の型に対してプライマリテンプレートが持たない追加の性質を持つ std::atomic テンプレートの部分特殊化を提供します。

2) すべてのポインタ型に対する部分特殊化 std::atomic<U*>。 これらの特殊化は標準レイアウト、トリビアルなデフォルトコンストラクタ (C++20未満)およびトリビアルなデストラクタを持ちます。 また、すべてのアトミック型に対して提供される演算に加えて、ポインタ型に適した fetch_add, fetch_sub などのアトミック算術演算も追加的にサポートされます。

3-4) std::shared_ptr および std::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以上)

整数型に対する特殊化

以下の整数型のいずれかに対して実体化した場合、 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
• ヘッダ <cstdint> の typedef によって必要とされるあらゆる追加の整数型

さらに、結果の特殊化 std::atomic<整数型> は標準レイアウト、トリビアルなデフォルトコンストラクタ (C++20未満)およびトリビアルなデストラクタを持ちます。 符号付き整数型は2の補数を使用して定義され、未定義の結果は発生しません。

浮動小数点型に対する特殊化 浮動小数点型 float, double, long double のいずれかに対して実体化した場合、 std::atomic は fetch_add, fetch_sub のような浮動小数点型に適した追加のアトミック演算を提供します。 さらに、結果の特殊化 std::atomic<浮動小数点型> は標準レイアウトおよびトリビアルなデストラクタを持ちます。 結果がその浮動小数点型で表現できない場合であっても、いかなる演算も未定義動作を発生することはありません。 有効な浮動小数点環境は呼び出し元スレッドの浮動小数点環境と異なる場合があります。

(C++20以上)

型エイリアス

bool および上記のすべての整数型に対する型エイリアスが以下のように提供されます。

型エイリアス	定義
std::atomic_bool	std::atomic<bool>
std::atomic_char	std::atomic<char>
std::atomic_schar	std::atomic<signed char>
std::atomic_uchar	std::atomic<unsigned char>
std::atomic_short	std::atomic<short>
std::atomic_ushort	std::atomic<unsigned short>
std::atomic_int	std::atomic<int>
std::atomic_uint	std::atomic<unsigned int>
std::atomic_long	std::atomic<long>
std::atomic_ulong	std::atomic<unsigned long>
std::atomic_llong	std::atomic<long long>
std::atomic_ullong	std::atomic<unsigned long long>
std::atomic_char8_t (C++20)	std::atomic<char8_t>
std::atomic_char16_t	std::atomic<char16_t>
std::atomic_char32_t	std::atomic<char32_t>
std::atomic_wchar_t	std::atomic<wchar_t>
std::atomic_int8_t	std::atomic<std::int8_t>
std::atomic_uint8_t	std::atomic<std::uint8_t>
std::atomic_int16_t	std::atomic<std::int16_t>
std::atomic_uint16_t	std::atomic<std::uint16_t>
std::atomic_int32_t	std::atomic<std::int32_t>
std::atomic_uint32_t	std::atomic<std::uint32_t>
std::atomic_int64_t	std::atomic<std::int64_t>
std::atomic_uint64_t	std::atomic<std::uint64_t>
std::atomic_int_least8_t	std::atomic<std::int_least8_t>
std::atomic_uint_least8_t	std::atomic<std::uint_least8_t>
std::atomic_int_least16_t	std::atomic<std::int_least16_t>
std::atomic_uint_least16_t	std::atomic<std::uint_least16_t>
std::atomic_int_least32_t	std::atomic<std::int_least32_t>
std::atomic_uint_least32_t	std::atomic<std::uint_least32_t>
std::atomic_int_least64_t	std::atomic<std::int_least64_t>
std::atomic_uint_least64_t	std::atomic<std::uint_least64_t>
std::atomic_int_fast8_t	std::atomic<std::int_fast8_t>
std::atomic_uint_fast8_t	std::atomic<std::uint_fast8_t>
std::atomic_int_fast16_t	std::atomic<std::int_fast16_t>
std::atomic_uint_fast16_t	std::atomic<std::uint_fast16_t>
std::atomic_int_fast32_t	std::atomic<std::int_fast32_t>
std::atomic_uint_fast32_t	std::atomic<std::uint_fast32_t>
std::atomic_int_fast64_t	std::atomic<std::int_fast64_t>
std::atomic_uint_fast64_t	std::atomic<std::uint_fast64_t>
std::atomic_intptr_t	std::atomic<std::intptr_t>
std::atomic_uintptr_t	std::atomic<std::uintptr_t>
std::atomic_size_t	std::atomic<std::size_t>
std::atomic_ptrdiff_t	std::atomic<std::ptrdiff_t>
std::atomic_intmax_t	std::atomic<std::intmax_t>
std::atomic_uintmax_t	std::atomic<std::uintmax_t>

ノート: 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 ロックフリーで wait/notify が最も効率的な符号付き整数アトミック型 std::atomic_unsigned_lock_free ロックフリーで wait/notify が最も効率的な符号なし整数アトミック型

(C++20以上)

メンバ型

メンバ型	定義
value_type	T (特殊化されているかどうかに関わらず)
difference_type	value_type (特殊化 atomic<整数型> および atomic<浮動小数点型> (C++20以上) に対してのみ) std::ptrdiff_t (特殊化 atomic<U*> に対してのみ)

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)	アトミックオブジェクトで待機しているスレッドの少なくとも1つに通知します (パブリックメンバ関数)
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)	アトミック値を1つインクリメントまたはデクリメントします (パブリックメンバ関数)
operator+=operator-=operator&=operator|=operator^=	アトミック値に対して加算、減算、ビット単位の論理積、論理和、排他的論理和を行います (パブリックメンバ関数)

ノート

std::atomic のすべてのメンバ関数に対して、同等な非メンバ関数が存在します。 これらの非メンバ関数は std::atomic の特殊化でないけれどもアトミック性を保証できる型に対して追加のオーバーロードを提供する場合があります。 そのような型は標準ライブラリでは std::shared_ptr<U> だけです。

gcc および clang では、ここで説明されている機能のいくつかは -latomic のリンクを必要とします。

欠陥報告

以下の動作変更欠陥報告は以前に発行された C++ 標準に遡って適用されました。

DR	適用先	発行時の動作	正しい動作
LWG 2441	C++11		added specializations for the (オプション) fixed width integer types
P0558R1	C++11		specification was substantially rewritten to resolve numerous issues in particular, member typedefs value_type and difference_type are added
LWG 3012	C++11	std::atomic<T> was permitted for any T that is trivially copyable but not copyable	such specializations are forbidden

関連項目

atomic_flag (C++11)

ロックフリーなアトミックブーリアン型 (クラス)