Класс QAtomicPointer

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

Этот класс был представлен в Qt 4.4.

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

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

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

Макросы

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

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

T *QAtomicPointer::loadRelaxed() const

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

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

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

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.

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

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

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

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

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