lib/ccan/likely/likely.h

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