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

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