Класс QAtomicPointer

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

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

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

• 32 открытых функций, унаследованных от QBasicAtomicPointer

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

• 6 статических открытых членов, унаследованных от QBasicAtomicPointer

Макросы

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

Класс 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 = 0)

Создаёт 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 если 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::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.