Класс 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, гарантируя, что обращение к памяти до атомарной операции (в порядке программы) не может быть переупорядочено после атомарной операции.