Changeset 55951 in vbox for trunk/include/iprt/cdefs.h

Timestamp:

May 19, 2015 11:48:06 PM (10 years ago)

Author:

vboxsync

Message:

iprt/cdefs.h,iprt/err.h: More or less deprecated RT_UNLIKELY and RT_FAILURE in favor of code organized around RT_LIKELY and RT_SUCCESS.

File:

• trunk/include/iprt/cdefs.h (modified) (5 diffs)

trunk/include/iprt/cdefs.h

@@ -1321 +1321 @@
  * A few notes about the usage:
  *
+ *      - Generally, order your code use RT_LIKELY() instead of RT_UNLIKELY().
+ *
  *      - Generally, use RT_UNLIKELY() with error condition checks (unless you
  *        have some _strong_ reason to do otherwise, in which case document it),
@@ -1328 +1330 @@
  *      - Other than that, if you don't know the likelihood of a test succeeding
  *        from empirical or other 'hard' evidence, don't make predictions unless
- *        you happen to be a Dirk Gently.
+ *        you happen to be a Dirk Gently character.
  *
  *      - These macros are meant to be used in places that get executed a lot. It
@@ -1336 +1338 @@
  *
  *      - Note that RT_SUCCESS() and RT_FAILURE() already makes use of RT_LIKELY()
- *        and RT_UNLIKELY(). Should you wish for prediction free status checks,
+ *        and RT_UNLIKELY().  Should you wish for prediction free status checks,
  *        use the RT_SUCCESS_NP() and RT_FAILURE_NP() macros instead.
  *
@@ -1342 +1344 @@
  * @returns the boolean result of the expression.
  * @param   expr        The expression that's very likely to be true.
- * @see RT_UNLIKELY
+ * @see     RT_UNLIKELY
  */
 /** @def RT_UNLIKELY
@@ -1351 +1353 @@
  * @returns the boolean result of the expression.
  * @param   expr        The expression that's very unlikely to be true.
- * @see RT_LIKELY
+ * @see     RT_LIKELY
+ *
+ * @remarks Please use RT_LIKELY() instead wherever possible!  That gives us a
+ *          better chance of the windows compilers to generate favorable code
+ *          too.  The belief is that the compiler will by default assume the
+ *          if-case is more likely than the else-case.
  */
 #if defined(__GNUC__)