Document QAtomic testAndSet

[ChangeLog][QtCore][QAtomic] Documented new overloads of testAndSet()
that were originally added for 5.3.

Fixes: QTBUG-103008
Pick-to: 6.4 6.3 6.2 5.15
Change-Id: I96c7b5828dc284651e6514389f405d7670d6784b
Reviewed-by: Marc Mutz <marc.mutz@qt.io>

1 files changed, 82 insertions, 0 deletions

diff --git a/src/corelib/thread/qatomic.cpp b/src/corelib/thread/qatomic.cpp
index 0184774b44..210218d72d 100644
--- a/src/corelib/thread/qatomic.cpp
+++ b/src/corelib/thread/qatomic.cpp
@@ -397,14 +397,21 @@
 
     Atomic test-and-set.
 
+    \note If you use this function in a loop, consider using the overload with the
+    additional \c{T &currentValue} argument instead, which avoids the extra load() on
+    failure.
+
     If the current value of this QAtomicInteger is the \a expectedValue,
     the test-and-set functions assign the \a newValue to this
     QAtomicInteger and return true. If the values are \e not the same,
     this function does nothing and returns \c false.
 
+//![memory-order-relaxed]
     This function uses \e relaxed \l {QAtomicInteger#Memory
     ordering}{memory ordering} semantics, leaving the compiler and
     processor to freely reorder memory accesses.
+//![memory-order-relaxed]
+
 */
 
 /*!
@@ -412,15 +419,21 @@
 
     Atomic test-and-set.
 
+    \note If you use this function in a loop, consider using the overload with the
+    additional \c{T &currentValue} argument instead, which avoids the extra load() on
+    failure.
+
     If the current value of this QAtomicInteger is the \a expectedValue,
     the test-and-set functions assign the \a newValue to this
     QAtomicInteger and return true. If the values are \e not the same,
     this function does nothing and returns \c false.
 
+//![memory-order-acquire]
     This function uses \e acquire \l {QAtomicInteger#Memory
     ordering}{memory ordering} semantics, which ensures that memory
     access following the atomic operation (in program order) may not
     be re-ordered before the atomic operation.
+//![memory-order-acquire]
 */
 
 /*!
@@ -428,15 +441,21 @@
 
     Atomic test-and-set.
 
+    \note If you use this function in a loop, consider using the overload with the
+    additional \c{T &currentValue} argument instead, which avoids the extra load() on
+    failure.
+
     If the current value of this QAtomicInteger is the \a expectedValue,
     the test-and-set functions assign the \a newValue to this
     QAtomicInteger and return true. If the values are \e not the same,
     this function does nothing and returns \c false.
 
+//![memory-order-release]
     This function uses \e release \l {QAtomicInteger#Memory
     ordering}{memory ordering} semantics, which ensures that memory
     access before the atomic operation (in program order) may not be
     re-ordered after the atomic operation.
+//![memory-order-release]
 */
 
 /*!
@@ -444,15 +463,78 @@
 
     Atomic test-and-set.
 
+    \note If you use this function in a loop, consider using the overload with the
+    additional \c{T &currentValue} argument instead, which avoids the extra load() on
+    failure.
+
     If the current value of this QAtomicInteger is the \a expectedValue,
     the test-and-set functions assign the \a newValue to this
     QAtomicInteger and return true. If the values are \e not the same,
     this function does nothing and returns \c false.
 
+//![memory-order-ordered]
     This function uses \e ordered \l {QAtomicInteger#Memory
     ordering}{memory ordering} semantics, which ensures that memory
     access before and after the atomic operation (in program order)
     may not be re-ordered.
+//![memory-order-ordered]
+
+*/
+
+/*!
+    \fn template <typename T> bool QAtomicInteger<T>::testAndSetRelaxed(T expectedValue, T newValue, T &currentValue)
+    \since 5.3
+
+    Atomic test-and-set.
+
+    If the current value of this QAtomicInteger is the \a expectedValue, the
+    test-and-set functions assign the \a newValue to this QAtomicInteger and
+    return \c true. If the values are \e not the same, the functions load the
+    current value of this QAtomicInteger into \a currentValue and return \c false.
+
+    \include qatomic.cpp memory-order-relaxed
+*/
+
+/*!
+    \fn template <typename T> bool QAtomicInteger<T>::testAndSetAcquire(T expectedValue, T newValue, T &currentValue)
+    \since 5.3
+
+    Atomic test-and-set.
+
+    If the current value of this QAtomicInteger is the \a expectedValue, the
+    test-and-set functions assign the \a newValue to this QAtomicInteger and
+    return \c true. If the values are \e not the same, the functions load the
+    current value of this QAtomicInteger into \a currentValue and return \c false.
+
+    \include qatomic.cpp memory-order-acquire
+*/
+
+/*!
+    \fn template <typename T> bool QAtomicInteger<T>::testAndSetRelease(T expectedValue, T newValue, T &currentValue)
+    \since 5.3
+
+    Atomic test-and-set.
+
+    If the current value of this QAtomicInteger is the \a expectedValue, the
+    test-and-set functions assign the \a newValue to this QAtomicInteger and
+    return \c true. If the values are \e not the same, the functions loads the
+    current value of this QAtomicInteger into \a currentValue and return \c false.
+
+    \include qatomic.cpp memory-order-release
+*/
+
+/*!
+    \fn template <typename T> bool QAtomicInteger<T>::testAndSetOrdered(T expectedValue, T newValue, T &currentValue)
+    \since 5.3
+
+    Atomic test-and-set.
+
+    If the current value of this QAtomicInteger is the \a expectedValue, the
+    test-and-set functions assign the \a newValue to this QAtomicInteger and
+    return \c true. If the values are \e not the same, it loads the current
+    value of this QAtomicInteger into \a currentValue and return \c false.
+
+    \include qatomic.cpp memory-order-ordered
 */
 
 /*!