5e4fc831c960dbe09d480fbc20182c596e3703f6
[ccan] / 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 #define likely(cond) __builtin_expect(!!(cond), 1)
34
35 /**
36  * unlikely - indicate that a condition is unlikely to be true.
37  * @cond: the condition
38  *
39  * This uses a compiler extension where available to indicate an unlikely
40  * code path and optimize appropriately; see likely() above.
41  *
42  * See Also:
43  *      likely(), likely_stats(), COLD (compiler.h)
44  *
45  * Example:
46  *      // Prints a warning if we overflow.
47  *      static inline void inc_int(unsigned int *val)
48  *      {
49  *              (*val)++;
50  *              if (unlikely(*val == 0))
51  *                      fprintf(stderr, "Overflow!");
52  *      }
53  */
54 #define unlikely(cond) __builtin_expect(!!(cond), 0)
55 #else
56 #define likely(cond) (!!(cond))
57 #define unlikely(cond) (!!(cond))
58 #endif
59 #else /* CCAN_LIKELY_DEBUG versions */
60 #define likely(cond) \
61         (_likely_trace(!!(cond), 1, stringify(cond), __FILE__, __LINE__))
62 #define unlikely(cond) \
63         (_likely_trace(!!(cond), 0, stringify(cond), __FILE__, __LINE__))
64
65 long _likely_trace(bool cond, bool expect,
66                    const char *condstr,
67                    const char *file, unsigned int line);
68 #endif
69
70 #ifdef CCAN_LIKELY_DEBUG
71 /**
72  * likely_stats - return description of abused likely()/unlikely()
73  * @min_hits: minimum number of hits
74  * @percent: maximum percentage correct
75  *
76  * When CCAN_LIKELY_DEBUG is defined, likely() and unlikely() trace their
77  * results: this causes a significant slowdown, but allows analysis of 
78  * whether the branches are labelled correctly.
79  *
80  * This function returns a malloc'ed description of the least-correct
81  * usage of likely() or unlikely().  It ignores places which have been
82  * called less than @min_hits times, and those which were predicted
83  * correctly more than @percent of the time.  It returns NULL when
84  * nothing meets those criteria.
85  *
86  * Note that this call is destructive; the returned offender is
87  * removed from the trace so that the next call to likely_stats() will
88  * return the next-worst likely()/unlikely() usage.
89  *
90  * Example:
91  *      // Print every place hit more than twice which was wrong > 5%.
92  *      static void report_stats(void)
93  *      {
94  *      #ifdef CCAN_LIKELY_DEBUG
95  *              const char *bad;
96  *
97  *              while ((bad = likely_stats(2, 95)) != NULL) {
98  *                      printf("Suspicious likely: %s", bad);
99  *                      free(bad);
100  *              }
101  *      #endif
102  *      }
103  */
104 const char *likely_stats(unsigned int min_hits, unsigned int percent);
105 #endif /* CCAN_LIKELY_DEBUG */
106 #endif /* CCAN_LIKELY_H */