From 275e0e48a97d06c122db64a3025fe22534ce37f0 Mon Sep 17 00:00:00 2001
From: Thiago Macieira <thiago.macieira@intel.com>
Date: Wed, 5 Apr 2023 17:11:32 -0300
Subject: [PATCH] Deprecate Q_ASSUME

No replacement provided because we didn't agree on how to do it. But the
current implementation is bad (with GCC, at least), so tell people to
stop using it.

[ChangeLog][Deprecations] The Q_ASSUME macro is now deprecated. Do not
use it in new code and consider removing it from existing code.

Change-Id: Idd5e1bb52be047d7b4fffffd175322ee3402756b
Reviewed-by: Volker Hilsheimer <volker.hilsheimer@qt.io>
---
 src/corelib/global/qassert.cpp             | 29 ++++++++--------------
 src/corelib/global/qcompilerdetection.qdoc |  2 +-
 2 files changed, 11 insertions(+), 20 deletions(-)

diff --git a/src/corelib/global/qassert.cpp b/src/corelib/global/qassert.cpp
index 4165429d4b..462f141294 100644
--- a/src/corelib/global/qassert.cpp
+++ b/src/corelib/global/qassert.cpp
@@ -139,29 +139,20 @@ void qBadAlloc()
 
 /*!
     \macro void Q_ASSUME(bool expr)
+    \deprecated
     \relates <QtAssert>
     \since 5.0
 
-    Causes the compiler to assume that \a expr is \c true. This macro is useful
-    for improving code generation, by providing the compiler with hints about
-    conditions that it would not otherwise know about. However, there is no
-    guarantee that the compiler will actually use those hints.
+    Causes the compiler to assume that \a expr is \c true.
 
-    This macro could be considered a "lighter" version of \l{Q_ASSERT()}. While
-    Q_ASSERT will abort the program's execution if the condition is \c false,
-    Q_ASSUME will tell the compiler not to generate code for those conditions.
-    Therefore, it is important that the assumptions always hold, otherwise
-    undefined behavior may occur.
+    This macro is known to produce worse code than when no assumption was
+    inserted in the code, with some compiler versions. The arguments passed to
+    it are always evaluated, even in release mode, with some compilers and not
+    others, so application code needs to be aware of those possible differences
+    in behavior.
 
-    If \a expr is a constantly \c false condition, Q_ASSUME will tell the compiler
-    that the current code execution cannot be reached. That is, Q_ASSUME(false)
-    is equivalent to Q_UNREACHABLE().
-
-    In debug builds the condition is enforced by an assert to facilitate debugging.
-
-    \note Q_LIKELY() tells the compiler that the expression is likely, but not
-    the only possibility. Q_ASSUME tells the compiler that it is the only
-    possibility.
+    Do not use it in new code. It is retained as-is for compatibility with old
+    code and will likely be removed in the next major version Qt.
 
     \sa Q_ASSERT(), Q_UNREACHABLE(), Q_LIKELY()
 */
@@ -199,7 +190,7 @@ void qBadAlloc()
     compilers that need them, without causing warnings for compilers that
     complain about its presence.
 
-    \sa Q_ASSERT(), Q_ASSUME(), qFatal(), Q_UNREACHABLE_RETURN()
+    \sa Q_ASSERT(), qFatal(), Q_UNREACHABLE_RETURN()
 */
 
 /*!
diff --git a/src/corelib/global/qcompilerdetection.qdoc b/src/corelib/global/qcompilerdetection.qdoc
index cb9108e76c..e6aa8e66d4 100644
--- a/src/corelib/global/qcompilerdetection.qdoc
+++ b/src/corelib/global/qcompilerdetection.qdoc
@@ -197,7 +197,7 @@
 
     \snippet code/src_corelib_global_qglobal.cpp qlikely
 
-    \sa Q_UNLIKELY(), Q_ASSUME()
+    \sa Q_UNLIKELY()
 */
 
 /*!