Класс 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(const QAtomicPointer<T> &other)

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

QAtomicPointer::QAtomicPointer(T *value = nullptr)

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

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

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

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 если fetch-and-add реализован с использованием атомарных инструкций процессора, в противном случае — false.

[static] bool QAtomicPointer::isFetchAndAddWaitFree()

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

[static] bool QAtomicPointer::isFetchAndStoreNative()

Возвращает 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::loadAcquire() const

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

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

[since 5.14] T *QAtomicPointer::loadRelaxed() const

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

Эта функция была добавлена в Qt 5.14.

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

[since 5.14] void QAtomicPointer::storeRelaxed(T *newValue)

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

Эта функция была добавлена в Qt 5.14.

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

void QAtomicPointer::storeRelease(T *newValue)

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

См. также storeRelaxed() и loadRelaxed().

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.

Функция использует семантику релаксированного упорядочивания памяти, позволяя компилятору и процессору свободно переупорядочивать обращения к памяти.

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

Атомарная операция test-and-set.

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

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