Класс 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.