Changeset 55951 in vbox

Timestamp:

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

Author:

vboxsync

svn:sync-xref-src-repo-rev:

100450

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.

Location:

trunk/include/iprt

Files:

• cdefs.h (modified) (5 diffs)
• err.h (modified) (2 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__)

trunk/include/iprt/err.h

@@ -162 +162 @@
 
 /** @def RT_FAILURE
- * Check for failure. We don't expect in normal cases, that is the code path depending on
- * this check is normally NOT taken. To prevent any prediction use RT_FAILURE_NP instead.
+ * Check for failure, predicting unlikely.
+ *
+ * We don't expect in normal cases, that is the code path depending on this
+ * check is normally NOT taken. To prevent any prediction use RT_FAILURE_NP
+ * instead.
  *
  * @returns true if rc indicates failure.
@@ -169 +172 @@
  *
  * @param   rc  The iprt status code to test.
+ *
+ * @remarks Please structure your code to use the RT_SUCCESS() macro instead of
+ *          RT_FAILURE() where possible, as that gives us a better shot at good
+ *          code with the windows compilers.
  */
 #define RT_FAILURE(rc)      ( RT_UNLIKELY(!RT_SUCCESS_NP(rc)) )
 
 /** @def RT_FAILURE_NP
- * Check for failure. Don't predict the result.
+ * Check for failure, no prediction.
  *
  * @returns true if rc indicates failure.