1 files changed, 101 insertions, 3 deletions

diff --git a/src/corelib/tools/qsharedpointer.cpp b/src/corelib/tools/qsharedpointer.cpp
index a610fc46e5..e0cd54022e 100644
--- a/src/corelib/tools/qsharedpointer.cpp
+++ b/src/corelib/tools/qsharedpointer.cpp
@@ -372,6 +372,64 @@
 */
 
 /*!
+    \class QEnableSharedFromThis
+    \inmodule QtCore
+    \brief A base class that allows obtaining a QSharedPointer for an object already managed by a shared pointer
+    \since 5.4
+
+    You can inherit this class when you need to create a QSharedPointer
+    from any instance of a class; for instance, from within the
+    object itself. The key point is that the technique of
+    just returning QSharedPointer<T>(this) can not be used, because
+    this winds up creating multiple distinct QSharedPointer objects
+    with separate reference counts. For this reason you must never
+    create more than one QSharedPointer from the same raw pointer.
+
+    QEnableSharedFromThis defines two member functions called
+    sharedFromThis() that return a QSharedPointer<T> and
+    QSharedPointer<const T>, depending on constness, to \c this:
+
+    \code
+    class Y: public QEnableSharedFromThis<Y>
+    {
+    public:
+        QSharedPointer<Y> f()
+        {
+            return sharedFromThis();
+        }
+    };
+
+    int main()
+    {
+        QSharedPointer<Y> p(new Y());
+        QSharedPointer<Y> y = p->f();
+        Q_ASSERT(p == y); // p and q must share ownership
+    }
+    \endcode
+
+    It is also possible to get a shared pointer from an object outside of
+    the class itself. This is especially useful in code that provides an
+    interface to scripts, where it is currently not possible to use shared
+    pointers. For example:
+
+    \code
+    class ScriptInterface : public QObject
+    {
+        Q_OBJECT
+
+        // ...
+
+    public slots:
+        void slotCalledByScript(Y *managedBySharedPointer)
+        {
+            QSharedPointer<Y> yPtr = managedBySharedPointer->sharedFromThis();
+            // Some other code unrelated to scripts that expects a QSharedPointer<Y> ...
+        }
+    };
+    \endcode
+*/
+
+/*!
     \fn QSharedPointer::QSharedPointer()
 
     Creates a QSharedPointer that points to null (0).
@@ -630,9 +688,15 @@
     This function will attempt to call a constructor for type \tt T that can
     accept all the arguments passed. Arguments will be perfectly-forwarded.
 
-    \note This function is only available with a C++11 compiler that supports
-    perfect forwarding of an arbitrary number of arguments. If the compiler
-    does not support the necessary C++11 features, you must use the overload
+    \note This function is only fully available with a C++11 compiler that
+    supports perfect forwarding of an arbitrary number of arguments.
+
+    If the compiler does not support the necessary C++11 features,
+    then a restricted version is available since Qt 5.4: you may pass
+    one (but just one) argument, and it will always be passed by const
+    reference.
+
+    If you target Qt before version 5.4, you must use the overload
     that calls the default constructor.
 */
 
@@ -771,6 +835,14 @@
 */
 
 /*!
+    \fn void QWeakPointer::swap(QWeakPointer<T> &other)
+    \since 5.4
+
+    Swaps this weak pointer instance with \a other. This function is
+    very fast and never fails.
+*/
+
+/*!
     \fn bool QWeakPointer::isNull() const
 
     Returns \c true if this object is holding a reference to a null
@@ -894,6 +966,15 @@
 */
 
 /*!
+    \fn QSharedPointer<T> QWeakPointer::lock() const
+    \since 5.4
+
+    Same as toStrongRef().
+
+    This function is provided for API compatibility with std::weak_ptr.
+*/
+
+/*!
     \fn void QWeakPointer::clear()
 
     Clears this QWeakPointer object, dropping the reference that it
@@ -901,6 +982,23 @@
 */
 
 /*!
+    \fn QSharedPointer<T> QEnableSharedFromThis::sharedFromThis()
+    \since 5.4
+
+    If \c this (that is, the subclass instance invoking this method) is being
+    managed by a QSharedPointer, returns a shared pointer instance pointing to
+    \c this; otherwise returns a QSharedPointer holding a null pointer.
+*/
+
+/*!
+    \fn QSharedPointer<const T> QEnableSharedFromThis::sharedFromThis() const
+    \overload
+    \since 5.4
+
+    Const overload of sharedFromThis().
+*/
+
+/*!
     \fn bool operator==(const QSharedPointer<T> &ptr1, const QSharedPointer<X> &ptr2)
     \relates QSharedPointer