QAtomic: introduce loadRelaxed() / storeRelaxed()

Plain load() / store() have already relaxed semantics. This
can be surprising -- std::atomic::load()/store() are actually
sequentially consistent -- and introduce a pain point
if someone wants to move from Qt atomics to std:: atomics.

So just add a suffix to the functions to clarify what's the
memory ordering involved with them.

The Ops::load / ::store are temporarily left in, because other
modules depends on them. We need to port those modules away,
then they can go (it's private API anyhow).

Similarly, not deprecating anything yet, except for marking
obsolete in the docs; there's a lot of code around using
load() / store() that needs to be ported first.

[ChangeLog][QtCore][QAtomicInteger] Added loadRelaxed() and
storeRelaxed(), to be used as replacements of load() / store().

[ChangeLog][QtCore][QAtomicPointer] Added loadRelaxed() and
storeRelaxed(), to be used as replacements of load() / store().

Change-Id: Iab0a78885050379e3740f0b039ba2bef28ce3bd2
Reviewed-by: Marc Mutz <marc.mutz@kdab.com>
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

1 files changed, 65 insertions, 10 deletions

diff --git a/src/corelib/thread/qatomic.cpp b/src/corelib/thread/qatomic.cpp
index c161bec537..b1a7edad91 100644
--- a/src/corelib/thread/qatomic.cpp
+++ b/src/corelib/thread/qatomic.cpp
@@ -258,12 +258,26 @@
 
 /*!
     \fn template <typename T> T QAtomicInteger<T>::load() const
+    \obsolete
+
+    Use loadRelaxed() instead.
 
     Atomically loads the value of this QAtomicInteger using relaxed memory
     ordering. The value is not modified in any way, but note that there's no
     guarantee that it remains so.
 
-    \sa store(), loadAcquire()
+    \sa storeRelaxed(), loadAcquire()
+*/
+
+/*!
+    \fn template <typename T> T QAtomicInteger<T>::loadRelaxed() const
+    \since 5.14
+
+    Atomically loads the value of this QAtomicInteger using relaxed memory
+    ordering. The value is not modified in any way, but note that there's no
+    guarantee that it remains so.
+
+    \sa storeRelaxed(), loadAcquire()
 */
 
 /*!
@@ -273,16 +287,29 @@
     ordering. The value is not modified in any way, but note that there's no
     guarantee that it remains so.
 
-    \sa store(), load()
+    \sa storeRelaxed(), loadRelaxed()
 */
 
 /*!
     \fn template <typename T> void QAtomicInteger<T>::store(T newValue)
+    \obsolete
+
+    Use storeRelaxed() instead.
 
     Atomically stores the \a newValue value into this atomic type, using
     relaxed memory ordering.
 
-    \sa storeRelease(), load()
+    \sa storeRelease(), loadRelaxed()
+*/
+
+/*!
+    \fn template <typename T> void QAtomicInteger<T>::storeRelaxed(T newValue)
+    \since 5.14
+
+    Atomically stores the \a newValue value into this atomic type, using
+    relaxed memory ordering.
+
+    \sa storeRelease(), loadRelaxed()
 */
 
 /*!
@@ -291,7 +318,7 @@
     Atomically stores the \a newValue value into this atomic type, using
     the "Release" memory ordering.
 
-    \sa store(), load()
+    \sa store(), loadAcquire()
 */
 
 /*!
@@ -303,7 +330,7 @@
     value is not modified in any way, but note that there's no guarantee that
     it remains so.
 
-    \sa load(), loadAcquire()
+    \sa loadRelaxed(), loadAcquire()
 */
 
 /*!
@@ -314,7 +341,7 @@
     sequentially consistent memory ordering if possible; or "Release" ordering
     if not. This function returns a reference to this object.
 
-    \sa store(), storeRelease()
+    \sa storeRelaxed(), storeRelease()
 */
 
 /*! \fn template <typename T> bool QAtomicInteger<T>::isReferenceCountingNative()
@@ -1278,31 +1305,59 @@
 
 /*!
     \fn template <typename T> T *QAtomicPointer<T>::load() const
+    \obsolete
+
+    Use loadRelaxed() instead.
 
     Atomically loads the value of this QAtomicPointer using relaxed memory
     ordering. The value is not modified in any way, but note that there's no
     guarantee that it remains so.
 
-    \sa store(), loadAcquire()
+    \sa storeRelaxed(), loadAcquire()
 */
 
 /*!
+    \fn template <typename T> T *QAtomicPointer<T>::loadRelaxed() const
+    \since 5.14
+
+    Atomically loads the value of this QAtomicPointer using relaxed memory
+    ordering. The value is not modified in any way, but note that there's no
+    guarantee that it remains so.
+
+    \sa storeRelaxed(), loadAcquire()
+*/
+
+
+/*!
     \fn template <typename T> T *QAtomicPointer<T>::loadAcquire() const
 
     Atomically loads the value of this QAtomicPointer using the "Acquire" memory
     ordering. The value is not modified in any way, but note that there's no
     guarantee that it remains so.
 
-    \sa store(), load()
+    \sa storeRelease(), loadRelaxed()
 */
 
 /*!
     \fn template <typename T> void QAtomicPointer<T>::store(T *newValue)
+    \obsolete
+
+    Use storeRelaxed() instead.
+
+    Atomically stores the \a newValue value into this atomic type, using
+    relaxed memory ordering.
+
+    \sa storeRelease(), loadRelaxed()
+*/
+
+/*!
+    \fn template <typename T> void QAtomicPointer<T>::storeRelaxed(T *newValue)
+    \since 5.14
 
     Atomically stores the \a newValue value into this atomic type, using
     relaxed memory ordering.
 
-    \sa storeRelease(), load()
+    \sa storeRelease(), loadRelaxed()
 */
 
 /*!
@@ -1311,7 +1366,7 @@
     Atomically stores the \a newValue value into this atomic type, using
     the "Release" memory ordering.
 
-    \sa store(), load()
+    \sa storeRelaxed(), loadRelaxed()
 */
 
 /*! \fn template <typename T> bool QAtomicPointer<T>::isTestAndSetNative()