likely: new module

[ccan] / ccan / likely / likely.h

diff --git a/ccan/likely/likely.h b/ccan/likely/likely.h
new file mode 100644 (file)
index 0000000..815ee22
--- /dev/null
+++ b/ccan/likely/likely.h
@@ -0,0 +1,129 @@
+#ifndef CCAN_LIKELY_H
+#define CCAN_LIKELY_H
+#include "config.h"
+#include <ccan/str/str.h>
+#include <stdbool.h>
+
+#ifndef DEBUG
+#if HAVE_BUILTIN_EXPECT
+/**
+ * likely - indicate that a condition is likely to be true.
+ * @cond: the condition
+ *
+ * This uses a compiler extension where available to indicate a likely
+ * code path and optimize appropriately; it's also useful for readers
+ * to quickly identify exceptional paths through functions.  The
+ * threshold for "likely" is usually considered to be between 90 and
+ * 99%; marginal cases should not be marked either way.
+ *
+ * See Also:
+ *     unlikely(), unlikely_func, likely_stats()
+ *
+ * Example:
+ *     // Returns false if we overflow.
+ *     static inline bool inc_int(unsigned int *val)
+ *     {
+ *             *(val)++;
+ *             if (likely(*val))
+ *                     return true;
+ *             return false;
+ *     }
+ */
+#define likely(cond) __builtin_expect(!!(cond), 1)
+
+/**
+ * unlikely - indicate that a condition is unlikely to be true.
+ * @cond: the condition
+ *
+ * This uses a compiler extension where available to indicate an unlikely
+ * code path and optimize appropriately; see likely() above.
+ *
+ * See Also:
+ *     likely(), unlikely_func, likely_stats()
+ *
+ * Example:
+ *     // Prints a warning if we overflow.
+ *     static inline void inc_int(unsigned int *val)
+ *     {
+ *             *(val)++;
+ *             if (unlikely(*val == 0))
+ *                     fprintf(stderr, "Overflow!");
+ *     }
+ */
+#define unlikely(cond) __builtin_expect(!!(cond), 0)
+#else
+#define likely(cond) (!!(cond))
+#define unlikely(cond) (!!(cond))
+#endif
+#else /* DEBUG versions */
+#define likely(cond) \
+       (_likely_trace(!!(cond), 1, stringify(cond), __FILE__, __LINE__))
+#define unlikely(cond) \
+       (_likely_trace(!!(cond), 0, stringify(cond), __FILE__, __LINE__))
+
+long _likely_trace(bool cond, bool expect,
+                  const char *condstr,
+                  const char *file, unsigned int line);
+#endif
+
+#if HAVE_ATTRIBUTE_COLD
+/**
+ * unlikely_func - indicate that a function is unlikely to be called.
+ *
+ * This uses a compiler extension where available to indicate an unlikely
+ * code path and optimize appropriately; see unlikely() above.
+ *
+ * It is usually used on logging or error routines.
+ *
+ * See Also:
+ *     unlikely()
+ *
+ * Example:
+ *     void unlikely_func die_moaning(const char *reason)
+ *     {
+ *             fprintf(stderr, "Dying: %s\n", reason);
+ *             exit(1);
+ *     }
+ */
+#define unlikely_func __attribute__((cold))
+#else
+#define unlikely_func
+#endif
+
+#ifdef DEBUG
+/**
+ * likely_stats - return description of abused likely()/unlikely()
+ * @min_hits: minimum number of hits
+ * @percent: maximum percentage correct
+ *
+ * When DEBUG is defined, likely() and unlikely() trace their results: this
+ * causes a significant slowdown, but allows analysis of whether the stats
+ * are correct (unlikely_func can't traced).
+ *
+ * This function returns a malloc'ed description of the least-correct
+ * usage of likely() or unlikely().  It ignores places which have been
+ * called less than @min_hits times, and those which were predicted
+ * correctly more than @percent of the time.  It returns NULL when
+ * nothing meets those criteria.
+ *
+ * Note that this call is destructive; the returned offender is
+ * removed from the trace so that the next call to likely_stats() will
+ * return the next-worst likely()/unlikely() usage.
+ *
+ * Example:
+ *     // Print every place hit more than twice which was wrong > 5%.
+ *     static void report_stats(void)
+ *     {
+ *     #ifdef DEBUG
+ *             const char *bad;
+ *
+ *             while ((bad = likely_stats(2, 95)) != NULL) {
+ *                     printf("Suspicious likely: %s", bad);
+ *                     free(bad);
+ *             }
+ *     #endif
+ *     }
+ */
+const char *likely_stats(unsigned int min_hits, unsigned int percent);
+#endif /* DEBUG */
+#endif /* CCAN_LIKELY_H */