tdb: enforce hashing, via example hash in old rwlocks entry in header.
[ccan] / 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 */