QAtomicPointer Class

template <typename T> class QAtomicPointer

QAtomicPointer クラスは、プラットフォームに依存しないポインタのアトミック操作を提供するテンプレート・クラスです。詳細...

Header: #include <QAtomicPointer>
CMake: find_package(Qt6 REQUIRED COMPONENTS Core)
target_link_libraries(mytarget PRIVATE Qt6::Core)
qmake: QT += 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
void storeRelaxed(T *newValue)
void storeRelease(T *newValue)
bool testAndSetAcquire(T *expectedValue, T *newValue)
bool testAndSetOrdered(T *expectedValue, T *newValue)
bool testAndSetRelaxed(T *expectedValue, T *newValue)
bool testAndSetRelease(T *expectedValue, T *newValue)
QAtomicPointer<T> &operator=(const QAtomicPointer<T> &other)

静的パブリックメンバ

マクロ

詳細説明

整数に対するアトミック操作については、QAtomicInteger クラスを参照のこと。

アトミック操作は、中断することなく完了する複雑な操作です。QAtomicPointerクラスは、ポインタに対してアトミックなtest-and-set、fetch-and-store、fetch-and-addを提供します。

アトミックAPI

メモリ順序付け

QAtomicPointerは、アトミックなtest-and-set関数、fetch-and-store関数、fetch-and-add関数の実装をいくつか提供しています。各実装は、アトミック命令を取り巻くメモリ・アクセスがプロセッサによってどのように実行されるかを記述するメモリ順序セマンティックを定義します。最近のアーキテクチャの多くはアウトオブオーダー実行とメモリ順序付けを許可しているため、アプリケーションがすべてのプロセッサで正しく機能するようにするには、正しいセマンティックを使用する必要があります。

  • Relaxed - メモリの順序が指定されていないため、コンパイラとプロセッサが自由にメモリ・アクセスの順序を変更できます。
  • Acquire - アトミック操作の後に続くメモリ・アクセス(プログラム順)は、アトミック操作の前に並べ替えることはできません。
  • Release - アトミック操作の前(プログラム順)のメモリ・アクセスは、アトミック操作の後に並べ替えることはできません。
  • Ordered - Acquire と Release のセマンティクスを組み合わせたもの。

テスト・アンド・セット

QAtomicPointer の現在の値が期待される値である場合、test-and-set 関数は QAtomicPointer に新しい値を割り当て、true を返します。値がnot 、これらの関数は何もせずfalseを返します。この操作は以下のコードに相当する:

if (currentValue == expectedValue) {
    currentValue = newValue;
    return true;
}
return false;

testAndSetRelaxed ()、testAndSetAcquire ()、testAndSetRelease ()、testAndSetOrdered ()。メモリ順序セマンティクスの違いについては、上記を参照のこと。

フェッチ・アンド・ストア

アトミック・フェッチ&ストア関数は、QAtomicPointerの現在の値を読み取り、新しい値を代入して元の値を返します。この操作は以下のコードに相当する:

T *originalValue = currentValue;
currentValue = newValue;
return originalValue;

fetchAndStoreRelaxed ()、fetchAndStoreAcquire ()、fetchAndStoreRelease ()、fetchAndStoreOrdered ()の4つのフェッチ・アンド・ストア関数があります。メモリ順序セマンティクスの違いについては、上記を参照のこと。

フェッチ・アンド・アド

アトミック・フェッチ&アド関数は、QAtomicPointerの現在値を読み取り、与えられた値を現在値に追加して元の値を返します。この操作は以下のコードに相当する:

T *originalValue = currentValue;
currentValue += valueToAdd;
return originalValue;

fetchAndAddRelaxed ()、fetchAndAddAcquire ()、fetchAndAddRelease ()、fetchAndAddOrdered ()。メモリ順序セマンティクスの違いについては上記を参照。

アトミックAPIの機能テスト

すべてのプロセッサで動作する、プラットフォームに依存しないアトミックAPIを提供することは困難である。QAtomicPointerが提供するAPIは、すべてのプロセッサでアトミックに動作することが保証されている。しかし、すべてのプロセッサがQAtomicPointerが提供するすべての操作のサポートを実装しているわけではないため、プロセッサに関する情報を公開する必要がある。

様々なマクロを使用することで、コンパイル時にどの機能がハードウェアでサポートされているかを確認することができます。これらのマクロは、ハードウェアが特定の操作を常にサポートしているのか、時々サポートしているのか、あるいはサポートしていないのかを教えてくれます。マクロはQ_ATOMIC_POINTER_OPERATION_IS_HOW_NATIVE という形式です。OPERATIONは TEST_AND_SETFETCH_AND_STOREFETCH_AND_ADD のいずれかであり、HOWはALWAYS、SOMETIMES、NOTのいずれかである。1つの操作につき、定義されたマクロは常に1つである。例えば、Q_ATOMIC_POINTER_TEST_AND_SET_IS_ALWAYS_NATIVE が定義されている場合、Q_ATOMIC_POINTER_TEST_AND_SET_IS_SOMETIMES_NATIVEQ_ATOMIC_POINTER_TEST_AND_SET_IS_NOT_NATIVE も定義されない。

一定の時間で完了する操作は、待ちがないと言われる。このような操作は、ロックやループを使用して実装されることはない。常にサポートされ、待ちのないアトミック操作に対して、Qt はQ_ATOMIC_POINTER_OPERATION_IS_ALWAYS_NATIVE に加えてQ_ATOMIC_POINTER_OPERATION_IS_WAIT_FREE を定義します。

アトミック演算が新しい世代のプロセッサでのみサポートされている場合、QAtomicPointer はisTestAndSetNative(),isFetchAndStoreNative(),isFetchAndAddNative() 関数を使用して、ハードウェアがサポートしているものを実行時に確認する方法も提供します。待ちのない実装は、isTestAndSetWaitFree ()、isFetchAndStoreWaitFree ()、isFetchAndAddWaitFree ()関数を使用して検出できます。

以下は、QAtomicPointer のすべての機能マクロの完全なリストです:

QAtomicInteger およびqYieldCpu()も参照してください

メンバ関数のドキュメント

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

与えられたvalue で QAtomicPointer を構築する。

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

other のコピーを構築する.

T *QAtomicPointer::fetchAndAddAcquire(qptrdiff valueToAdd)

アトミックフェッチアンドアド。

このQAtomicPointer の現在値を読み取り、valueToAdd を現在値に追加して元の値を返す。

この関数は、acquire memory ordering セマンティクスを使用します。このセマンティクスは、アトミック操作(プログラム順)に続くメモリ・アクセスが、アトミック操作の前に再順序付けされないことを保証します。

T *QAtomicPointer::fetchAndAddOrdered(qptrdiff valueToAdd)

アトミック・フェッチ・アンド・アッド。

このQAtomicPointer の現在値を読み取り、valueToAdd を現在値に加算して元の値を返す。

この関数は順序付き memory ordering セマンティクスを使用し、アトミック操作の前後(プログラム順)のメモリアクセスが再順序付けされないことを保証する。

T *QAtomicPointer::fetchAndAddRelaxed(qptrdiff valueToAdd)

アトミック・フェッチ・アンド・アッド。

このQAtomicPointer の現在値を読み取り、valueToAdd を現在値に加算し、元の値を返す。

この関数は、memory ordering のセマンティクスを緩和し、コンパイラとプロセッサが自由にメモリ・アクセスの順序を変更できるようにしています。

T *QAtomicPointer::fetchAndAddRelease(qptrdiff valueToAdd)

アトミック・フェッチ・アンド・アッド。

このQAtomicPointer の現在値を読み取り、valueToAdd を現在値に加算して元の値を返す。

この関数はリリース memory ordering セマンティクスを使用します。このセマンティクスは、アトミック操作の前(プログラム順)のメモリ・アクセスが、アトミック操作の後に再順序付けされないことを保証します。

T *QAtomicPointer::fetchAndStoreAcquire(T *newValue)

アトミック・フェッチ&ストア。

このQAtomicPointer の現在値を読み取り、newValue に代入して元の値を返す。

この関数は、acquire memory ordering セマンティクスを使用します。このセマンティクスは、アトミック操作の後に続くメモリ・アクセス(プログラム順)が、アトミック操作の前に再順序付けされないことを保証します。

T *QAtomicPointer::fetchAndStoreOrdered(T *newValue)

アトミック・フェッチ&ストア。

このQAtomicPointer の現在値を読み取り、newValue に代入して元の値を返す。

この関数は順序付き memory ordering セマンティクスを使用し、アトミック操作の前後(プログラム順)のメモリ・アクセスが再順序付けされないことを保証する。

T *QAtomicPointer::fetchAndStoreRelaxed(T *newValue)

アトミック・フェッチ&ストア。

このQAtomicPointer の現在値を読み取り、それをnewValue に代入し、元の値を返す。

この関数は、memory ordering のセマンティクスを緩和し、コンパイラとプロセッサが自由にメモリ・アクセスの順序を変更できるようにしています。

T *QAtomicPointer::fetchAndStoreRelease(T *newValue)

アトミック・フェッチ&ストア。

このQAtomicPointer の現在値を読み取り、それをnewValue に代入し、元の値を返す。

この関数はリリース memory ordering セマンティクスを使用し、アトミック操作の前(プログラム順)のメモリ・アクセスが、アトミック操作の後に再順序付けされないことを保証します。

[static constexpr] bool QAtomicPointer::isFetchAndAddNative()

フェッチ・アンド・アドがアトミック・プロセッサ命令を使用して実装されている場合はtrue を返し、そうでない場合は false を返します。

[static constexpr] bool QAtomicPointer::isFetchAndAddWaitFree()

アトミックフェッチアンドアドがウェイトフリーであればtrue を返し、そうでなければ false を返す。

[static constexpr] bool QAtomicPointer::isFetchAndStoreNative()

アトミックプロセッサ命令を使用してフェッチ&ストアが実装されている場合はtrue を返し、そうでない場合は false を返す。

[static constexpr] bool QAtomicPointer::isFetchAndStoreWaitFree()

アトミックフェッチアンドストアが待ちなしの場合はtrue を返し、そうでない場合は false を返します。

[static constexpr] bool QAtomicPointer::isTestAndSetNative()

アトミックプロセッサ命令を使用してテストアンドセットが実装されている場合はtrue を返し、そうでない場合は false を返します。

[static constexpr] 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)

Release "メモリ順序を使用して、newValue の値をこのアトミック型にアトミックに格納する。

storeRelaxed() およびloadRelaxed() も参照

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

アトミック・テスト・アンド・セット。

このQAtomicPointer の現在の値がexpectedValue である場合、test-and-set 関数はnewValue をこのQAtomicPointer に代入し、true を返す。値が同じでない場合、この関数は何もせず、false を返す。

この関数は、acquire memory ordering セマンティクスを使用します。このセマンティクスは、アトミック操作の後に続くメモリ・アクセス(プログラム順)が、アトミック操作の前に再順序付けされないことを保証します。

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

アトミック・テスト&セット。

このQAtomicPointer の現在の値がexpectedValue である場合、test-and-set 関数はnewValue をこのQAtomicPointer に割り当て、true を返します。値が同じでない場合、この関数は何もせず、false を返します。

この関数は順序付き memory ordering セマンティクスを使用し、アトミック操作の前後(プログラム順)のメモリ・アクセスが再順序付けされないことを保証します。

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

アトミック・テスト・アンド・セット。

このQAtomicPointer の現在の値がexpectedValue である場合、test-and-set 関数はnewValue をこのQAtomicPointer に代入し、true を返す。値が同じでない場合、この関数は何もせず、false を返す。

この関数は、memory ordering のセマンティクスを緩和しているため、コンパイラとプロセッサは自由にメモリ・アクセスの順序を変更することができます。

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

アトミック・テスト・アンド・セット。

このQAtomicPointer の現在の値がexpectedValue である場合、test-and-set 関数はnewValue をこのQAtomicPointer に代入し、true を返します。値が同じでない場合、この関数は何もせず、false を返します。

この関数はリリース memory ordering セマンティクスを使用し、アトミック操作前のメモリ・アクセス(プログラム順)がアトミック操作後に再順序付けされないことを保証する。

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

other をこのQAtomicPointer に割り当て、このQAtomicPointer への参照を返す。

マクロ文書

Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_ALWAYS_NATIVE

このマクロは、プロセッサがポインタのアトミック・フェッチ&アドをサポートしている場合にのみ定義される。

Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_NOT_NATIVE

このマクロは、ハードウェアがポインタのアトミック・フェッチ&アドをサポートしていない場合に定義される。

Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_SOMETIMES_NATIVE

このマクロは、特定の世代のプロセッサのみがポインタのアトミック・フェッチ&アドをサポートしている場合に定義される。QAtomicPointer::isFetchAndAddNative() 関数を使用して、プロセッサが何をサポートしているかを確認する。

Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_WAIT_FREE

このマクロは、Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_ALWAYS_NATIVE とともに定義され、ポインタのアトミックフェッチアンドアドがウェイトフリーであることを示す。

Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_ALWAYS_NATIVE

このマクロは、プロセッサがポインタのアトミック・フェッチ&ストアをサポートしている場合にのみ定義される。

Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_NOT_NATIVE

このマクロは、ハードウェアがポインタのアトミック・フェッチ&ストアをサポートしていない場合に定義される。

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_ATOMIC_POINTER_TEST_AND_SET_IS_WAIT_FREE

このマクロは、Q_ATOMIC_POINTER_TEST_AND_SET_IS_ALWAYS_NATIVE と共に定義され、ポインタのアトミックテストアンドセットが wait-free であることを示します。

本ドキュメントに含まれる文書の著作権は、それぞれの所有者に帰属します 本書で提供されるドキュメントは、Free Software Foundation が発行したGNU Free Documentation License version 1.3に基づいてライセンスされています。 Qtおよびそれぞれのロゴは、フィンランドおよびその他の国におけるThe Qt Company Ltd.の 商標です。その他すべての商標は、それぞれの所有者に帰属します。