Класс QAtomicPointer

Класс QAtomicPointer — это шаблонный класс, который предоставляет платформенно-независимые атомарные операции над указателями. Подробнее...

• Список всех членов, включая унаследованные

Открытые функции

Статические открытые члены

Макросы

Подробное описание

Класс QAtomicPointer — это шаблонный класс, который предоставляет платформенно-независимые атомарные операции над указателями.

Для атомарных операций с целыми числами см. класс 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.

Test-and-set

Если текущее значение QAtomicPointer соответствует ожидаемому значению, функции test-and-set присваивают новое значение QAtomicPointer и возвращают true. Если значения не совпадают, эти функции ничего не делают и возвращают false. Эта операция эквивалентна следующему коду:

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

Существует 4 функции test-and-set: testAndSetRelaxed(), testAndSetAcquire(), testAndSetRelease() и testAndSetOrdered(). См. выше объяснение различных семантик порядка памяти.

Fetch-and-store

Атомарные функции fetch-and-store считывают текущее значение QAtomicPointer, а затем присваивают новое значение, возвращая исходное значение. Эта операция эквивалентна следующему коду:

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

Существует 4 функции fetch-and-store: fetchAndStoreRelaxed(), fetchAndStoreAcquire(), fetchAndStoreRelease(), и fetchAndStoreOrdered(). См. выше для объяснения различных семантик порядка памяти.

Fetch-and-add

Функции атомарного fetch-and-add считывают текущее значение QAtomicPointer, а затем добавляют заданное значение к текущему значению, возвращая исходное значение. Эта операция эквивалентна следующему коду:

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

Существует 4 функции fetch-and-add: fetchAndAddRelaxed(), fetchAndAddAcquire(), fetchAndAddRelease(), и fetchAndAddOrdered(). См. выше для объяснения различных семантик порядка памяти.

Тесты функций атомарного API

Предоставление независимого от платформы атомарного API, работающего на всех процессорах, является сложной задачей. API, предоставляемый QAtomicPointer, гарантированно работает атомарно на всех процессорах. Однако, так как не все процессоры поддерживают все операции, предоставляемые QAtomicPointer, необходимо предоставить информацию о процессоре.

Вы можете проверить во время компиляции, какие функции поддерживаются вашим оборудованием, используя различные макросы. Они скажут вам, всегда ли, иногда или никогда не поддерживается конкретная операция на вашем оборудовании. Макросы имеют вид Q_ATOMIC_POINTER_OPERATION_IS_HOW_NATIVE. OPERATION — это одна из TEST_AND_SET, FETCH_AND_STORE или FETCH_AND_ADD, а HOW — одна из ALWAYS, SOMETIMES или NOT. Для каждой операции всегда будет определён ровно один макрос. Например, если Q_ATOMIC_POINTER_TEST_AND_SET_IS_ALWAYS_NATIVE определён, ни Q_ATOMIC_POINTER_TEST_AND_SET_IS_SOMETIMES_NATIVE, ни Q_ATOMIC_POINTER_TEST_AND_SET_IS_NOT_NATIVE не будут определены.

Операция, которая выполняется за постоянное время, называется бесперебойной. Такие операции не реализуются с помощью блокировок или циклов любого рода. Для атомарных операций, которые всегда поддерживаются и являются бесперебойными, Qt определяет Q_ATOMIC_POINTER_OPERATION_IS_WAIT_FREE в дополнение к Q_ATOMIC_POINTER_OPERATION_IS_ALWAYS_NATIVE.

В тех случаях, когда атомарная операция поддерживается только в новых поколениях процессоров, QAtomicPointer также предоставляет способ проверки на выполнение того, что поддерживается вашим оборудованием во время выполнения с помощью функций isTestAndSetNative(), isFetchAndStoreNative() и isFetchAndAddNative(). Бесперебойные реализации могут быть обнаружены с помощью функций isTestAndSetWaitFree(), isFetchAndStoreWaitFree() и isFetchAndAddWaitFree().

Ниже приведён полный список всех макросов функций для QAtomicPointer:

• Q_ATOMIC_POINTER_TEST_AND_SET_IS_ALWAYS_NATIVE
• Q_ATOMIC_POINTER_TEST_AND_SET_IS_SOMETIMES_NATIVE
• Q_ATOMIC_POINTER_TEST_AND_SET_IS_NOT_NATIVE
• Q_ATOMIC_POINTER_TEST_AND_SET_IS_WAIT_FREE
• Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_ALWAYS_NATIVE
• Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_SOMETIMES_NATIVE
• Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_NOT_NATIVE
• Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_WAIT_FREE
• Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_ALWAYS_NATIVE
• Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_SOMETIMES_NATIVE
• Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_NOT_NATIVE
• Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_WAIT_FREE

См. также QAtomicInteger.

Документация по функциям-членам

QAtomicPointer::QAtomicPointer(T *value = nullptr)

Создаёт QAtomicPointer с заданным значением value.

QAtomicPointer::QAtomicPointer(const QAtomicPointer<T> &other)

Создаёт копию other.

T *QAtomicPointer::fetchAndAddAcquire(qptrdiff valueToAdd)

Атомарное fetch-and-add.

Считывает текущее значение этого QAtomicPointer, затем добавляет valueToAdd к текущему значению и возвращает исходное значение.

Эта функция использует семантику порядка памяти acquire, которая гарантирует, что доступ к памяти, следующий за атомарной операцией (в порядке программы), не может быть переупорядочен до атомарной операции.

T *QAtomicPointer::fetchAndAddOrdered(qptrdiff valueToAdd)

Атомарное fetch-and-add.

Считывает текущее значение этого QAtomicPointer, затем добавляет valueToAdd к текущему значению и возвращает исходное значение.

Эта функция использует семантику порядка памяти ordered, которая гарантирует, что доступ к памяти до и после атомарной операции (в порядке программы) не может быть переупорядочен.

T *QAtomicPointer::fetchAndAddRelaxed(qptrdiff valueToAdd)

Атомарное fetch-and-add.

Считывает текущее значение этого QAtomicPointer, затем добавляет valueToAdd к текущему значению и возвращает исходное значение.

Эта функция использует семантику порядка памяти relaxed, оставляя компилятору и процессору свободу переупорядочивать доступ к памяти.

T *QAtomicPointer::fetchAndAddRelease(qptrdiff valueToAdd)

Атомарное fetch-and-add.

Считывает текущее значение этого QAtomicPointer, затем добавляет valueToAdd к текущему значению и возвращает исходное значение.

Эта функция использует семантику порядка памяти release, которая гарантирует, что доступ к памяти до атомарной операции (в порядке программы) не может быть переупорядочен после атомарной операции.

T *QAtomicPointer::fetchAndStoreAcquire(T *newValue)

Атомарное fetch-and-store.

Считывает текущее значение этого QAtomicPointer и присваивает ему newValue, возвращая исходное значение.

Эта функция использует семантику порядка памяти acquire, которая гарантирует, что доступ к памяти, следующий за атомарной операцией (в порядке программы), не может быть переупорядочен до атомарной операции.

T *QAtomicPointer::fetchAndStoreOrdered(T *newValue)

Атомарное fetch-and-store.

Считывает текущее значение этого QAtomicPointer и присваивает ему newValue, возвращая исходное значение.

Эта функция использует семантику порядка памяти ordered, которая гарантирует, что доступ к памяти до и после атомарной операции (в порядке программы) не может быть переупорядочен.

T *QAtomicPointer::fetchAndStoreRelaxed(T *newValue)

Атомарное fetch-and-store.

Считывает текущее значение этого QAtomicPointer и присваивает ему newValue, возвращая исходное значение.

Эта функция использует семантику порядка памяти relaxed, оставляя компилятору и процессору свободу переупорядочивать доступ к памяти.

T *QAtomicPointer::fetchAndStoreRelease(T *newValue)

Атомарное fetch-and-store.

Считывает текущее значение этого QAtomicPointer и присваивает ему newValue, возвращая исходное значение.

Эта функция использует семантику порядка памяти release, которая гарантирует, что доступ к памяти до атомарной операции (в порядке программы) не может быть переупорядочен после атомарной операции.

[static] bool QAtomicPointer::isFetchAndAddNative()

Возвращает true значение true, если fetch-and-add реализован с помощью атомарных инструкций процессора, иначе false.

[static] bool QAtomicPointer::isFetchAndAddWaitFree()

Возвращает true значение true, если атомарное fetch-and-add является бесперебойным, иначе false.

[static] bool QAtomicPointer::isFetchAndStoreNative()

Возвращает true значение true, если fetch-and-store реализован с помощью атомарных инструкций процессора, иначе false.

[static] bool QAtomicPointer::isFetchAndStoreWaitFree()

Возвращает true если атомарная операция fetch-and-store не блокируется, в противном случае возвращает false.

[static] bool QAtomicPointer::isTestAndSetNative()

Возвращает true если операция test-and-set реализована с использованием атомарных инструкций процессора, в противном случае возвращает false.

[static] bool QAtomicPointer::isTestAndSetWaitFree()

Возвращает true если атомарная операция test-and-set не блокируется, в противном случае возвращает false.

T *QAtomicPointer::load() const

Атомарно загружает значение этого QAtomicPointer с использованием релаксированного порядка памяти. Значение не изменяется, но нет гарантии, что оно останется неизменным.

См. также store() и loadAcquire().

T *QAtomicPointer::loadAcquire() const

Атомарно загружает значение этого QAtomicPointer с использованием порядка памяти «Acquire». Значение не изменяется, но нет гарантии, что оно останется неизменным.

См. также store() и load().

void QAtomicPointer::store(T *newValue)

Атомарно сохраняет значение newValue в этом атомарном типе с использованием релаксированного порядка памяти.

См. также storeRelease() и load().

void QAtomicPointer::storeRelease(T *newValue)

Атомарно сохраняет значение newValue в этом атомарном типе с использованием порядка памяти «Release».

См. также store() и load().

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

Атомарное test-and-set.

Если текущее значение этого QAtomicPointer равно expectedValue, test-and-set присваивает newValue этому QAtomicPointer и возвращает true. Если значения не совпадают, функция ничего не делает и возвращает false.

Эта функция использует семантику порядка памяти acquire, что гарантирует, что доступ к памяти после атомарной операции (в порядке программы) не может быть переупорядочен до атомарной операции.

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

Атомарное test-and-set.

Если текущее значение этого QAtomicPointer равно expectedValue, test-and-set присваивает newValue этому QAtomicPointer и возвращает true. Если значения не совпадают, функция ничего не делает и возвращает false.

Эта функция использует семантику ordered порядка памяти, которая гарантирует, что доступ к памяти до и после атомарной операции (в порядке программы) не может быть переупорядочен.

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

Атомарное test-and-set.

Если текущее значение этого QAtomicPointer равно expectedValue, test-and-set присваивает newValue этому QAtomicPointer и возвращает true. Если значения не совпадают, функция ничего не делает и возвращает false.

Эта функция использует семантику relaxed порядка памяти, позволяя компилятору и процессору свободно переупорядочивать доступ к памяти.

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

Атомарное test-and-set.

Если текущее значение этого QAtomicPointer равно expectedValue, test-and-set присваивает newValue этому QAtomicPointer и возвращает true. Если значения не совпадают, функция ничего не делает и возвращает false.

Эта функция использует семантику release порядка памяти, которая гарантирует, что доступ к памяти перед атомарной операцией (в порядке программы) не может быть переупорядочен после атомарной операции.

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

Присваивает other этому QAtomicPointer и возвращает ссылку на этот QAtomicPointer.