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 #ifndef COLD
   6 #if HAVE_ATTRIBUTE_COLD
   7 /**
   8  * COLD - a function is unlikely to be called.
   9  *
  10  * Used to mark an unlikely code path and optimize appropriately.
  11  * It is usually used on logging or error routines.
  12  *
  13  * Example:
  14  * static void COLD moan(const char *reason)
  15  * {
  16  *      fprintf(stderr, "Error: %s (%s)\n", reason, strerror(errno));
  17  * }
  18  */
  19 #define COLD __attribute__((cold))
  20 #else
  21 #define COLD
  22 #endif
  23 #endif
  24
  25 #ifndef NORETURN
  26 #if HAVE_ATTRIBUTE_NORETURN
  27 /**
  28  * NORETURN - a function does not return
  29  *
  30  * Used to mark a function which exits; useful for suppressing warnings.
  31  *
  32  * Example:
  33  * static void NORETURN fail(const char *reason)
  34  * {
  35  *      fprintf(stderr, "Error: %s (%s)\n", reason, strerror(errno));
  36  *      exit(1);
  37  * }
  38  */
  39 #define NORETURN __attribute__((noreturn))
  40 #else
  41 #define NORETURN
  42 #endif
  43 #endif
  44
  45 #ifndef PRINTF_FMT
  46 #if HAVE_ATTRIBUTE_PRINTF
  47 /**
  48  * PRINTF_FMT - a function takes printf-style arguments
  49  * @nfmt: the 1-based number of the function's format argument.
  50  * @narg: the 1-based number of the function's first variable argument.
  51  *
  52  * This allows the compiler to check your parameters as it does for printf().
  53  *
  54  * Example:
  55  * void PRINTF_FMT(2,3) my_printf(const char *prefix, const char *fmt, ...);
  56  */
  57 #define PRINTF_FMT(nfmt, narg) \
  58         __attribute__((format(__printf__, nfmt, narg)))
  59 #else
  60 #define PRINTF_FMT(nfmt, narg)
  61 #endif
  62 #endif
  63
  64 #ifndef CONST_FUNCTION
  65 #if HAVE_ATTRIBUTE_CONST
  66 /**
  67  * CONST_FUNCTION - a function's return depends only on its argument
  68  *
  69  * This allows the compiler to assume that the function will return the exact
  70  * same value for the exact same arguments.  This implies that the function
  71  * must not use global variables, or dereference pointer arguments.
  72  */
  73 #define CONST_FUNCTION __attribute__((const))
  74 #else
  75 #define CONST_FUNCTION
  76 #endif
  77 #endif
  78
  79 #if HAVE_ATTRIBUTE_UNUSED
  80 #ifndef UNNEEDED
  81 /**
  82  * UNNEEDED - a variable/function may not be needed
  83  *
  84  * This suppresses warnings about unused variables or functions, but tells
  85  * the compiler that if it is unused it need not emit it into the source code.
  86  *
  87  * Example:
  88  * // With some preprocessor options, this is unnecessary.
  89  * static UNNEEDED int counter;
  90  *
  91  * // With some preprocessor options, this is unnecessary.
  92  * static UNNEEDED void add_to_counter(int add)
  93  * {
  94  *      counter += add;
  95  * }
  96  */
  97 #define UNNEEDED __attribute__((unused))
  98 #endif
  99
 100 #ifndef NEEDED
 101 #if HAVE_ATTRIBUTE_USED
 102 /**
 103  * NEEDED - a variable/function is needed
 104  *
 105  * This suppresses warnings about unused variables or functions, but tells
 106  * the compiler that it must exist even if it (seems) unused.
 107  *
 108  * Example:
 109  *      // Even if this is unused, these are vital for debugging.
 110  *      static NEEDED int counter;
 111  *      static NEEDED void dump_counter(void)
 112  *      {
 113  *              printf("Counter is %i\n", counter);
 114  *      }
 115  */
 116 #define NEEDED __attribute__((used))
 117 #else
 118 /* Before used, unused functions and vars were always emitted. */
 119 #define NEEDED __attribute__((unused))
 120 #endif
 121 #endif
 122
 123 #ifndef UNUSED
 124 /**
 125  * UNUSED - a parameter is unused
 126  *
 127  * Some compilers (eg. gcc with -W or -Wunused) warn about unused
 128  * function parameters.  This suppresses such warnings and indicates
 129  * to the reader that it's deliberate.
 130  *
 131  * Example:
 132  *      // This is used as a callback, so needs to have this prototype.
 133  *      static int some_callback(void *unused UNUSED)
 134  *      {
 135  *              return 0;
 136  *      }
 137  */
 138 #define UNUSED __attribute__((unused))
 139 #endif
 140 #else
 141 #ifndef UNNEEDED
 142 #define UNNEEDED
 143 #endif
 144 #ifndef NEEDED
 145 #define NEEDED
 146 #endif
 147 #ifndef UNUSED
 148 #define UNUSED
 149 #endif
 150 #endif
 151
 152 #ifndef IS_COMPILE_CONSTANT
 153 #if HAVE_BUILTIN_CONSTANT_P
 154 /**
 155  * IS_COMPILE_CONSTANT - does the compiler know the value of this expression?
 156  * @expr: the expression to evaluate
 157  *
 158  * When an expression manipulation is complicated, it is usually better to
 159  * implement it in a function.  However, if the expression being manipulated is
 160  * known at compile time, it is better to have the compiler see the entire
 161  * expression so it can simply substitute the result.
 162  *
 163  * This can be done using the IS_COMPILE_CONSTANT() macro.
 164  *
 165  * Example:
 166  *      enum greek { ALPHA, BETA, GAMMA, DELTA, EPSILON };
 167  *
 168  *      // Out-of-line version.
 169  *      const char *greek_name(enum greek greek);
 170  *
 171  *      // Inline version.
 172  *      static inline const char *_greek_name(enum greek greek)
 173  *      {
 174  *              switch (greek) {
 175  *              case ALPHA: return "alpha";
 176  *              case BETA: return "beta";
 177  *              case GAMMA: return "gamma";
 178  *              case DELTA: return "delta";
 179  *              case EPSILON: return "epsilon";
 180  *              default: return "**INVALID**";
 181  *              }
 182  *      }
 183  *
 184  *      // Use inline if compiler knows answer.  Otherwise call function
 185  *      // to avoid copies of the same code everywhere.
 186  *      #define greek_name(g)                                           \
 187  *               (IS_COMPILE_CONSTANT(greek) ? _greek_name(g) : greek_name(g))
 188  */
 189 #define IS_COMPILE_CONSTANT(expr) __builtin_constant_p(expr)
 190 #else
 191 /* If we don't know, assume it's not. */
 192 #define IS_COMPILE_CONSTANT(expr) 0
 193 #endif
 194 #endif
 195
 196 #ifndef WARN_UNUSED_RESULT
 197 #if HAVE_WARN_UNUSED_RESULT
 198 /**
 199  * WARN_UNUSED_RESULT - warn if a function return value is unused.
 200  *
 201  * Used to mark a function where it is extremely unlikely that the caller
 202  * can ignore the result, eg realloc().
 203  *
 204  * Example:
 205  * // buf param may be freed by this; need return value!
 206  * static char *WARN_UNUSED_RESULT enlarge(char *buf, unsigned *size)
 207  * {
 208  *      return realloc(buf, (*size) *= 2);
 209  * }
 210  */
 211 #define WARN_UNUSED_RESULT __attribute__((warn_unused_result))
 212 #else
 213 #define WARN_UNUSED_RESULT
 214 #endif
 215 #endif
 216 #endif /* CCAN_COMPILER_H */