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

   1 #ifndef CCAN_COMPILER_H
   2 #define CCAN_COMPILER_H
   3 #include "config.h"
   4
   5 #if HAVE_ATTRIBUTE_COLD
   6 /**
   7  * COLD_ATTRIBUTE - a function is unlikely to be called.
   8  *
   9  * Used to mark an unlikely code path and optimize appropriately.
  10  * It is usually used on logging or error routines.
  11  *
  12  * Example:
  13  * static void COLD_ATTRIBUTE moan(const char *reason)
  14  * {
  15  *      fprintf(stderr, "Error: %s (%s)\n", reason, strerror(errno));
  16  * }
  17  */
  18 #define COLD_ATTRIBUTE __attribute__((cold))
  19 #else
  20 #define COLD_ATTRIBUTE
  21 #endif
  22
  23 #if HAVE_ATTRIBUTE_PRINTF
  24 /**
  25  * PRINTF_ATTRIBUTE - a function takes printf-style arguments
  26  * @nfmt: the 1-based number of the function's format argument.
  27  * @narg: the 1-based number of the function's first variable argument.
  28  *
  29  * This allows the compiler to check your parameters as it does for printf().
  30  *
  31  * Example:
  32  * void PRINTF_ATTRIBUTE(2,3) my_printf(const char *prefix,
  33  *                                      const char *fmt, ...);
  34  */
  35 #define PRINTF_ATTRIBUTE(nfmt, narg) \
  36         __attribute__((format(__printf__, nfmt, narg)))
  37 #else
  38 #define PRINTF_ATTRIBUTE(nfmt, narg)
  39 #endif
  40
  41 #if HAVE_ATTRIBUTE_CONST
  42 /**
  43  * IDEMPOTENT_ATTRIBUTE - a function's return depends only on its argument
  44  *
  45  * This allows the compiler to assume that the function will return the exact
  46  * same value for the exact same arguments.  This implies that the function
  47  * must not use global variables, or dereference pointer arguments.
  48  */
  49 #define IDEMPOTENT_ATTRIBUTE __attribute__((const))
  50 #else
  51 #define IDEMPOTENT_ATTRIBUTE
  52 #endif
  53
  54 #if HAVE_ATTRIBUTE_UNUSED
  55 /**
  56  * UNNEEDED_ATTRIBUTE - a parameter/variable/function may not be needed
  57  *
  58  * This suppresses warnings about unused variables or parameters, but tells
  59  * the compiler that if it is unused it need not emit it into the source code.
  60  *
  61  * Example:
  62  * // With some preprocessor options, this is unnecessary.
  63  * static UNNEEDED_ATTRIBUTE int counter;
  64  *
  65  * // With some preprocessor options, this is unnecessary.
  66  * static UNNEEDED_ATTRIBUTE void add_to_counter(int add)
  67  * {
  68  *      counter += add;
  69  * }
  70  */
  71 #define UNNEEDED_ATTRIBUTE __attribute__((unused))
  72
  73 #if HAVE_ATTRIBUTE_USED
  74 /**
  75  * NEEDED_ATTRIBUTE - a parameter/variable/function is needed
  76  *
  77  * This suppresses warnings about unused variables or parameters, but tells
  78  * the compiler that it must exist even if it (seems) unused.
  79  *
  80  * Example:
  81  *      // Even if this is unused, these are vital for debugging.
  82  *      static UNNEEDED_ATTRIBUTE int counter;
  83  *      static UNNEEDED_ATTRIBUTE void dump_counter(void)
  84  *      {
  85  *              printf("Counter is %i\n", counter);
  86  *      }
  87  */
  88 #define NEEDED_ATTRIBUTE __attribute__((used))
  89 #else
  90 /* Before used, unused functions and vars were always emitted. */
  91 #define NEEDED_ATTRIBUTE __attribute__((unused))
  92 #endif
  93 #else
  94 #define UNNEEDED_ATTRIBUTE
  95 #define NEEDED_ATTRIBUTE
  96 #endif
  97
  98 #if HAVE_BUILTIN_CONSTANT_P
  99 /**
 100  * IS_COMPILE_CONSTANT - does the compiler know the value of this expression?
 101  * @expr: the expression to evaluate
 102  *
 103  * When an expression manipulation is complicated, it is usually better to
 104  * implement it in a function.  However, if the expression being manipulated is
 105  * known at compile time, it is better to have the compiler see the entire
 106  * expression so it can simply substitute the result.
 107  *
 108  * This can be done using the IS_COMPILE_CONSTANT() macro.
 109  *
 110  * Example:
 111  *      enum greek { ALPHA, BETA, GAMMA, DELTA, EPSILON };
 112  *
 113  *      // Out-of-line version.
 114  *      const char *greek_name(enum greek greek);
 115  *
 116  *      // Inline version.
 117  *      static inline char *_greek_name(enum greek greek)
 118  *      {
 119  *              switch (greek) {
 120  *              case ALPHA: return "alpha";
 121  *              case BETA: return "beta";
 122  *              case GAMMA: return "gamma";
 123  *              case DELTA: return "delta";
 124  *              case EPSILON: return "epsilon";
 125  *              default: return "**INVALID**";
 126  *              }
 127  *      }
 128  *
 129  *      // Use inline if compiler knows answer.  Otherwise call function
 130  *      // to avoid copies of the same code everywhere.
 131  *      #define greek_name(g)                                           \
 132  *               (IS_COMPILE_CONSTANT(greek) ? _greek_name(g) : greek_name(g))
 133  */
 134 #define IS_COMPILE_CONSTANT(expr) __builtin_constant_p(expr)
 135 #else
 136 /* If we don't know, assume it's not. */
 137 #define IS_COMPILE_CONSTANT(expr) 0
 138 #endif
 139
 140 #if HAVE_WARN_UNUSED_RESULT
 141 /**
 142  * WARN_UNUSED_RESULT - warn if a function return value is unused.
 143  *
 144  * Used to mark a function where it is extremely unlikely that the caller
 145  * can ignore the result, eg realloc().
 146  *
 147  * Example:
 148  * // buf param may be freed by this; need return value!
 149  * static char *WARN_UNUSED_RESULT enlarge(char *buf, unsigned *size)
 150  * {
 151  *      return realloc(buf, (*size) *= 2);
 152  * }
 153  */
 154 #define WARN_UNUSED_RESULT __attribute__((warn_unused_result))
 155 #else
 156 #define WARN_UNUSED_RESULT
 157 #endif
 158 #endif /* CCAN_COMPILER_H */