From 3b8d37b1f04acf60ceb144bfa5ed82e72e59a255 Mon Sep 17 00:00:00 2001
From: Sona Kurazyan <sona.kurazyan@qt.io>
Date: Mon, 2 Nov 2020 11:06:26 +0100
Subject: Update the porting guide for QFuture

Document the source compatibility breaks introduced by the recent
changes (ff0ba7e2d7b91fd5809cb314935a1ca1a436f6c9 and
30a1683f65fa0d01eceb7e1293abc84108d76e7f) in the porting guide.

Task-number: QTBUG-87096
Change-Id: I5b725c863b1077d59074d4bd17a4456e3d87918c
Reviewed-by: Allan Sandfeld Jensen <allan.jensen@qt.io>
---
 src/corelib/doc/src/qt6-changes.qdoc | 44 ++++++++++++++++++++++++++++++++----
 1 file changed, 40 insertions(+), 4 deletions(-)

(limited to 'src/corelib/doc/src/qt6-changes.qdoc')

diff --git a/src/corelib/doc/src/qt6-changes.qdoc b/src/corelib/doc/src/qt6-changes.qdoc
index 6354737249..dd4e7b54e2 100644
--- a/src/corelib/doc/src/qt6-changes.qdoc
+++ b/src/corelib/doc/src/qt6-changes.qdoc
@@ -395,11 +395,47 @@
 
     \section1 QFuture and Related Classes
 
-    \section2 QFuture and QFutureWatcher
+    \section2 QFuture
 
-    In Qt 6, there are no changes that introduce source compatibility breaks
-    in code that was using QFuture and QFutureWatcher classes. However there
-    were some improvements which caused the following behavioral changes:
+    To avoid unintended usage of QFuture, there were some changes to
+    QFuture API in Qt 6, which may introduce source compatibility breaks.
+
+    \section3 Implicit conversions between QFuture and other types
+
+    Conversion of \c QFuture<T> to \c T has been disabled. The casting
+    operator was calling QFuture::result(), which may lead to undefined
+    behavior if the user has moved the results from QFuture via
+    QFuture::takeResult() before trying to do the conversion. Use
+    QFuture::result() or QFuture::takeResult() methods explicitly,
+    where you need to convert \c QFuture<T> to \c T.
+
+    The implicit conversion from \c QFuture<T> to \c QFuture<void> has
+    been also disabled. If you really intend to do the conversion, use the
+    explicit \c {QFuture<void>(const QFuture<T> &)} constructor:
+
+    \code
+    QFuture<int> future = ...
+    QFuture<void> voidFuture = QFuture<void>(future);
+    \endcode
+
+    \section3 Equality operators
+
+    The equality operators of QFuture have been removed. They were comparing
+    the underlying d-pointers instead of comparing the results, which is not
+    what users might expect. If you need to compare QFuture objects, use
+    \c QFuture::result() or \c QFuture::takeResult() methods. For example:
+
+    \code
+    QFuture<int> future1 = ...;
+    QFuture<int> future2 = ...;
+    if (future1.result() == future2.result())
+        // ...
+    \endcode
+
+    \section2 Behavioral Changes to QFuture and QFutureWatcher
+
+    In Qt 6, there were some improvements to QFuture and QFutureWatcher which
+    caused the following behavioral changes:
 
     \list
 
-- 
cgit v1.2.3