git.ozlabs.org Git - ccan/blob - ccan/likely/likely.h

   1 #ifndef CCAN_LIKELY_H
   2 #define CCAN_LIKELY_H
   3 #include "config.h"
   4 #include <ccan/str/str.h>
   5 #include <stdbool.h>
   6
   7 #ifndef DEBUG
   8 #if HAVE_BUILTIN_EXPECT
   9 /**
  10  * likely - indicate that a condition is likely to be true.
  11  * @cond: the condition
  12  *
  13  * This uses a compiler extension where available to indicate a likely
  14  * code path and optimize appropriately; it's also useful for readers
  15  * to quickly identify exceptional paths through functions.  The
  16  * threshold for "likely" is usually considered to be between 90 and
  17  * 99%; marginal cases should not be marked either way.
  18  *
  19  * See Also:
  20  *      unlikely(), unlikely_func, likely_stats()
  21  *
  22  * Example:
  23  *      // Returns false if we overflow.
  24  *      static inline bool inc_int(unsigned int *val)
  25  *      {
  26  *              *(val)++;
  27  *              if (likely(*val))
  28  *                      return true;
  29  *              return false;
  30  *      }
  31  */
  32 #define likely(cond) __builtin_expect(!!(cond), 1)
  33
  34 /**
  35  * unlikely - indicate that a condition is unlikely to be true.
  36  * @cond: the condition
  37  *
  38  * This uses a compiler extension where available to indicate an unlikely
  39  * code path and optimize appropriately; see likely() above.
  40  *
  41  * See Also:
  42  *      likely(), unlikely_func, likely_stats()
  43  *
  44  * Example:
  45  *      // Prints a warning if we overflow.
  46  *      static inline void inc_int(unsigned int *val)
  47  *      {
  48  *              *(val)++;
  49  *              if (unlikely(*val == 0))
  50  *                      fprintf(stderr, "Overflow!");
  51  *      }
  52  */
  53 #define unlikely(cond) __builtin_expect(!!(cond), 0)
  54 #else
  55 #define likely(cond) (!!(cond))
  56 #define unlikely(cond) (!!(cond))
  57 #endif
  58 #else /* DEBUG versions */
  59 #define likely(cond) \
  60         (_likely_trace(!!(cond), 1, stringify(cond), __FILE__, __LINE__))
  61 #define unlikely(cond) \
  62         (_likely_trace(!!(cond), 0, stringify(cond), __FILE__, __LINE__))
  63
  64 long _likely_trace(bool cond, bool expect,
  65                    const char *condstr,
  66                    const char *file, unsigned int line);
  67 #endif
  68
  69 #if HAVE_ATTRIBUTE_COLD
  70 /**
  71  * unlikely_func - indicate that a function is unlikely to be called.
  72  *
  73  * This uses a compiler extension where available to indicate an unlikely
  74  * code path and optimize appropriately; see unlikely() above.
  75  *
  76  * It is usually used on logging or error routines.
  77  *
  78  * See Also:
  79  *      unlikely()
  80  *
  81  * Example:
  82  *      void unlikely_func die_moaning(const char *reason)
  83  *      {
  84  *              fprintf(stderr, "Dying: %s\n", reason);
  85  *              exit(1);
  86  *      }
  87  */
  88 #define unlikely_func __attribute__((cold))
  89 #else
  90 #define unlikely_func
  91 #endif
  92
  93 #ifdef DEBUG
  94 /**
  95  * likely_stats - return description of abused likely()/unlikely()
  96  * @min_hits: minimum number of hits
  97  * @percent: maximum percentage correct
  98  *
  99  * When DEBUG is defined, likely() and unlikely() trace their results: this
 100  * causes a significant slowdown, but allows analysis of whether the stats
 101  * are correct (unlikely_func can't traced).
 102  *
 103  * This function returns a malloc'ed description of the least-correct
 104  * usage of likely() or unlikely().  It ignores places which have been
 105  * called less than @min_hits times, and those which were predicted
 106  * correctly more than @percent of the time.  It returns NULL when
 107  * nothing meets those criteria.
 108  *
 109  * Note that this call is destructive; the returned offender is
 110  * removed from the trace so that the next call to likely_stats() will
 111  * return the next-worst likely()/unlikely() usage.
 112  *
 113  * Example:
 114  *      // Print every place hit more than twice which was wrong > 5%.
 115  *      static void report_stats(void)
 116  *      {
 117  *      #ifdef DEBUG
 118  *              const char *bad;
 119  *
 120  *              while ((bad = likely_stats(2, 95)) != NULL) {
 121  *                      printf("Suspicious likely: %s", bad);
 122  *                      free(bad);
 123  *              }
 124  *      #endif
 125  *      }
 126  */
 127 const char *likely_stats(unsigned int min_hits, unsigned int percent);
 128 #endif /* DEBUG */
 129 #endif /* CCAN_LIKELY_H */