QAtomicPointer Class

template <typename T> class QAtomicPointer

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

ヘッダー #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クラスは、ポインタに対してアトミックなテスト・アンド・セット、フェッチ・アンド・ストア、フェッチ・アンド・アドを提供します。

アトミック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()

test-and-setがアトミック・プロセッサ命令を使って実装されていれば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 とともに定義され、ポインタに対するアトミックなテスト・アンド・セットが待ちなしであることを示す。

© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.