Back to Doc.qt.io
Contact Us Blog Download Qt

QAtomicScopedValueRollback Class

template <typename T> class QAtomicScopedValueRollback

Provides a QScopedValueRollback for atomic variables. More...

Header: #include <QAtomicScopedValueRollback>
CMake: find_package(Qt6 REQUIRED COMPONENTS Core)
target_link_libraries(mytarget PRIVATE Qt6::Core)
qmake: QT += core
Since: Qt 6.7

Public Functions

QAtomicScopedValueRollback(std::atomic<T> &var, std::memory_order mo = std::memory_order_seq_cst)
QAtomicScopedValueRollback(std::atomic<T> &var, T value, std::memory_order mo = std::memory_order_seq_cst)
QAtomicScopedValueRollback(QBasicAtomicInteger<T> &var, std::memory_order mo = std::memory_order_seq_cst)
QAtomicScopedValueRollback(QBasicAtomicInteger<T> &var, T value, std::memory_order mo = std::memory_order_seq_cst)
QAtomicScopedValueRollback(QBasicAtomicPointer<std::remove_pointer_t<T>> &var, std::memory_order mo = std::memory_order_seq_cst)
QAtomicScopedValueRollback(QBasicAtomicPointer<std::remove_pointer_t<T>> &var, T value, std::memory_order mo = std::memory_order_seq_cst)
~QAtomicScopedValueRollback()
void commit()

Detailed Description

The QAtomicScopedValueRollback class resets an atomic variable to its prior value on destruction. It can be used to revert state when an exception is thrown without the need to write try-catch blocks.

It can also be used to manage variables that are temporarily set, such as reentrancy guards. By using this class, the variable will be reset whether the function is exited normally, exited early by a return statement, or exited by an exception.

The class works on std::atomic and the Qt atomic classes: QBasicAtomicInteger, QAtomicInteger, QAtomicInt, QBasicAtomicPointer and QAtomicPointer.

The memory accesses to the atomic variable var are specified using the value of mo. The memory order follows this mapping:

  • When writing to the atomic variable:
    • An acquire ordering performs a relaxed operation instead.
    • A hybrid acquire-release ordering performs a release operation instead.
  • When reading from the atomic variable:
    • A release ordering performs a relaxed operation instead.
    • A consume ordering performs a consume operation.
    • A hybrid acquire-release ordering performs an acquire operation instead.


Otherwise, the default memory order is sequential consistent ordering.

Note: You should never name the template arguments explicitly, but exclusively use Class Template Argument Deduction (CTAD) and let the compiler pick the template argument.

Note: There is a chance that other threads modify the variable too, which means you may lose updates performed by other threads between the call to the QAtomicScopedValueRollback constructor and commit() or between commit() and the destructor.

See also QScopedValueRollback.

Member Function Documentation

[explicit constexpr] QAtomicScopedValueRollback::QAtomicScopedValueRollback(QBasicAtomicInteger<T> &var, std::memory_order mo = std::memory_order_seq_cst)

[explicit constexpr] QAtomicScopedValueRollback::QAtomicScopedValueRollback(QBasicAtomicPointer<std::remove_pointer_t<T>> &var, std::memory_order mo = std::memory_order_seq_cst)

[explicit constexpr] QAtomicScopedValueRollback::QAtomicScopedValueRollback(std::atomic<T> &var, std::memory_order mo = std::memory_order_seq_cst)

Records the value of var in order to restore it on destruction.

This is equivalent to:

T old_value = var.load(mo);
// And in the destructor: var.store(old_value, mo);

The mo adjustment for the load is described in the Memory Order section.

[explicit constexpr] QAtomicScopedValueRollback::QAtomicScopedValueRollback(QBasicAtomicInteger<T> &var, T value, std::memory_order mo = std::memory_order_seq_cst)

[explicit constexpr] QAtomicScopedValueRollback::QAtomicScopedValueRollback(QBasicAtomicPointer<std::remove_pointer_t<T>> &var, T value, std::memory_order mo = std::memory_order_seq_cst)

[explicit constexpr] QAtomicScopedValueRollback::QAtomicScopedValueRollback(std::atomic<T> &var, T value, std::memory_order mo = std::memory_order_seq_cst)

Assigns value to var and stores the prior value of var internally for reverting on destruction.

This is equivalent to:

T old_value = var.exchange(new_value, mo);
// And in the destructor: var.store(old_value, mo);

QAtomicScopedValueRollback::~QAtomicScopedValueRollback()

Restores the stored value that was current at construction time, or at the last call to commit(), to the managed variable.

This is equivalent to:

// In the constructor: T old_value = var.load(mo);
// or: T old_value = exchange(new_value, mo);
var.store(old_value, mo);

Where mo is the same as the one initially passed to the constructor. See Memory Order for the meaning of mo.

void QAtomicScopedValueRollback::commit()

Updates the stored value to the managed variable's current value, loaded with the same memory order as on construction.

This updated value will be restored on destruction, instead of the original prior value.

This is equivalent to:

// Given constructor: T old_value = var.load(mo);
old_value = var.load(mo);  // referesh it
// And, in the destructor: var.store(old_value, mo);

Where mo is the same as the one initially passed to the constructor. See Memory Order for the meaning of mo.

© 2024 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.