1// Copyright (C) 2016 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
7 \class QAtomicScopedValueRollback
9 \brief Provides a QScopedValueRollback for atomic variables.
14 The QAtomicScopedValueRollback class resets an atomic variable to its
15 prior value on destruction. It can be used to revert state when an
16 exception is thrown without the need to write try-catch blocks.
18 It can also be used to manage variables that are temporarily set, such as
19 reentrancy guards. By using this class, the variable will be reset whether the
20 function is exited normally, exited early by a return statement, or exited by
23 The class works on std::atomic and the Qt atomic classes: QBasicAtomicInteger,
24 \l QAtomicInteger, \l QAtomicInt, QBasicAtomicPointer and \l QAtomicPointer.
27 The memory accesses to the atomic variable \a var are specified using the value
28 of \c mo. The memory order follows this mapping:
31 \li When writing to the atomic variable:
33 \li An acquire ordering performs a relaxed operation instead.
34 \li A hybrid acquire-release ordering performs a release operation instead.
36 \li When reading from the atomic variable:
38 \li A release ordering performs a relaxed operation instead.
39 \li A consume ordering performs a consume operation.
40 \li A hybrid acquire-release ordering performs an acquire operation instead.
44 Otherwise, the default memory order is sequential consistent ordering.
46 \note You should never name the template arguments explicitly, but exclusively
47 use Class Template Argument Deduction (CTAD) and let the compiler pick the
50 \note There is a chance that other threads modify the variable too, which means
51 you may lose updates performed by other threads between the call to the
52 QAtomicScopedValueRollback constructor and commit() or between commit() and the
55 \sa QScopedValueRollback
59 \fn template <typename T> QAtomicScopedValueRollback<T>::QAtomicScopedValueRollback(std::atomic<T> &var, std::memory_order mo = std::memory_order_seq_cst)
60 \fn template <typename T> QAtomicScopedValueRollback<T>::QAtomicScopedValueRollback(QBasicAtomicInteger<T> &var, std::memory_order mo = std::memory_order_seq_cst)
61 \fn template <typename T> QAtomicScopedValueRollback<T>::QAtomicScopedValueRollback(QBasicAtomicPointer<std::remove_pointer_t<T>> &var, std::memory_order mo = std::memory_order_seq_cst)
63 Records the value of \a var in order to restore it on destruction.
65 This is equivalent to:
67 T old_value = var.load(mo);
68 // And in the destructor: var.store(old_value, mo);
70 The \c{mo} adjustment for the load is described in the \l {Memory Order} section.
74 \fn template <typename T> QAtomicScopedValueRollback<T>::QAtomicScopedValueRollback(std::atomic<T> &var, T value, std::memory_order mo = std::memory_order_seq_cst)
75 \fn template <typename T> QAtomicScopedValueRollback<T>::QAtomicScopedValueRollback(QBasicAtomicInteger<T> &var, T value, std::memory_order mo = std::memory_order_seq_cst)
76 \fn template <typename T> QAtomicScopedValueRollback<T>::QAtomicScopedValueRollback(QBasicAtomicPointer<std::remove_pointer_t<T>> &var, T value, std::memory_order mo = std::memory_order_seq_cst)
78 Assigns \a value to \a var and stores the prior value of \a var internally for
79 reverting on destruction.
81 This is equivalent to:
83 T old_value = var.exchange(new_value, mo);
84 // And in the destructor: var.store(old_value, mo);
89 \fn template <typename T> QAtomicScopedValueRollback<T>::~QAtomicScopedValueRollback()
91 Restores the stored value that was current at construction time, or
92 at the last call to commit(), to the managed variable.
94 This is equivalent to:
96 // In the constructor: T old_value = var.load(mo);
97 // or: T old_value = exchange(new_value, mo);
98 var.store(old_value, mo);
100 Where \c{mo} is the same as the one initially passed to the constructor.
101 See \l{Memory Order} for the meaning of \c{mo}.
105 \fn template <typename T> void QAtomicScopedValueRollback<T>::commit()
107 Updates the stored value to the managed variable's current value, loaded
108 with the same memory order as on construction.
110 This updated value will be restored on destruction, instead of the original
113 This is equivalent to:
115 // Given constructor: T old_value = var.load(mo);
116 old_value = var.load(mo); // referesh it
117 // And, in the destructor: var.store(old_value, mo);
119 Where \c{mo} is the same as the one initially passed to the constructor.
120 See \l{Memory Order} for the meaning of \c{mo}.