From b62c3a85452aecf4f6c863645db34857b05d5ebf Mon Sep 17 00:00:00 2001 From: Jaishree Vyas Date: Mon, 8 Aug 2022 21:36:40 +0200 Subject: [PATCH] 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 --- src/corelib/thread/qatomic.cpp | 82 ++++++++++++++++++++++++++++++++++ src/corelib/thread/qatomic.h | 5 +++ 2 files changed, 87 insertions(+) diff --git a/src/corelib/thread/qatomic.cpp b/src/corelib/thread/qatomic.cpp index 0184774b447..210218d72d4 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 ¤tValue} 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 ¤tValue} 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 ¤tValue} 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 ¤tValue} 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 bool QAtomicInteger::testAndSetRelaxed(T expectedValue, T newValue, T ¤tValue) + \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 bool QAtomicInteger::testAndSetAcquire(T expectedValue, T newValue, T ¤tValue) + \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 bool QAtomicInteger::testAndSetRelease(T expectedValue, T newValue, T ¤tValue) + \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 bool QAtomicInteger::testAndSetOrdered(T expectedValue, T newValue, T ¤tValue) + \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 */ /*! diff --git a/src/corelib/thread/qatomic.h b/src/corelib/thread/qatomic.h index a4c9c23fbe0..b11e3f1bdfe 100644 --- a/src/corelib/thread/qatomic.h +++ b/src/corelib/thread/qatomic.h @@ -70,6 +70,11 @@ public: bool testAndSetRelease(T expectedValue, T newValue); bool testAndSetOrdered(T expectedValue, T newValue); + bool testAndSetRelaxed(T expectedValue, T newValue, T ¤tValue); + bool testAndSetAcquire(T expectedValue, T newValue, T ¤tValue); + bool testAndSetRelease(T expectedValue, T newValue, T ¤tValue); + bool testAndSetOrdered(T expectedValue, T newValue, T ¤tValue); + static constexpr bool isFetchAndStoreNative(); static constexpr bool isFetchAndStoreWaitFree();