Q(E)SDP(V2): fill the API gap left by take()

take() returns a pointer to the shared data object *without*
decrementing the reference counter. The primary use case
is adopting the object from a Q(E)SDP into a different reference
counting mechanism. This is fine, but if we support the
"extraction" part, we shall also support the "adoption" part.
Also, the API for the shared data pointer classes should
match.

Add an adopting tag type and suitable constructors to the
shared data pointer classes, and add take() to the classes
lacking it.

Drive by, apply qExchange to take()'s implementation.

[ChangeLog][QtCore][QAdoptSharedDataTag] New class.
It is now possible to adopt pointers to shared data into
a QExplicitlySharedDataPointer or a QSharedDataPointer object
without incrementing the object's reference counter.

Change-Id: I62b8b005c1bfbe2add58566206fca27634bb7e70
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>

1 files changed, 38 insertions, 1 deletions

diff --git a/src/corelib/tools/qshareddata.cpp b/src/corelib/tools/qshareddata.cpp
index 42360a4cae..6db2a9adb9 100644
--- a/src/corelib/tools/qshareddata.cpp
+++ b/src/corelib/tools/qshareddata.cpp
@@ -65,6 +65,20 @@ QT_BEGIN_NAMESPACE
 */
 
 /*!
+    \class QAdoptSharedDataTag
+    \inmodule QtCore
+    \threadsafe
+    \brief The QAdoptSharedDataTag is a helper tag class.
+    \since 6.0
+
+    QAdoptSharedDataTag objects are used in QSharedDataPointer
+    and QExplicitlySharedDataPointer to adopt a pointer to
+    shared data.
+
+    See QSharedDataPointer and QExplicitlySharedDataPointer for details.
+*/
+
+/*!
     \class QSharedDataPointer
     \inmodule QtCore
     \brief The QSharedDataPointer class represents a pointer to an implicitly shared object.
@@ -302,6 +316,18 @@ QT_BEGIN_NAMESPACE
     Same as data(). This function is provided for STL compatibility.
 */
 
+/*! \fn template <class T> const T* QSharedDataPointer<T>::take()
+    \since 6.0
+
+    Returns a pointer to the shared object, and resets \e this to be \nullptr.
+    (That is, this function sets the \e{d pointer} of \e this to \nullptr.)
+
+    \note The reference count of the returned object will \b{not} be
+    decremented. This function can be used together with the
+    constructor that takes a QAdoptSharedDataTag tag object to transfer
+    the shared data object without intervening atomic operations.
+*/
+
 /*! \fn template <class T> const T* QSharedDataPointer<T>::constData() const
     Returns a const pointer to the shared data object.
     This function does \e not call detach().
@@ -365,6 +391,15 @@ QT_BEGIN_NAMESPACE
     \a data and increments \a{data}'s reference count.
 */
 
+/*! \fn template <class T> QSharedDataPointer<T>::QSharedDataPointer(T* data, QAdoptSharedDataTag)
+    \since 6.0
+    Constructs a QSharedDataPointer with \e{d pointer} set to
+    \a data. \a data's reference counter is \b{not} incremented;
+    this can be used to adopt pointers obtained from take().
+
+    \sa take()
+*/
+
 /*! \fn template <class T> QSharedDataPointer<T>::QSharedDataPointer(const QSharedDataPointer<T>& o)
     Sets the \e{d pointer} of \e this to the \e{d pointer} in
     \a o and increments the reference count of the shared
@@ -615,7 +650,9 @@ QT_BEGIN_NAMESPACE
     (That is, this function sets the \e{d pointer} of \e this to \nullptr.)
 
     \note The reference count of the returned object will \b{not} be
-    decremented.
+    decremented. This function can be used together with the
+    constructor that takes a QAdoptSharedDataTag tag object to transfer
+    the shared data object without intervening atomic operations.
  */
 
 /*! \fn template <class T> QExplicitlySharedDataPointer<T>::operator bool () const