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>

1 files changed, 10 insertions, 19 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()
 */
 
 /*!