1 #ifndef CCAN_COMPILER_H
2 #define CCAN_COMPILER_H
6 #if HAVE_ATTRIBUTE_COLD
8 * COLD - a function is unlikely to be called.
10 * Used to mark an unlikely code path and optimize appropriately.
11 * It is usually used on logging or error routines.
14 * static void COLD moan(const char *reason)
16 * fprintf(stderr, "Error: %s (%s)\n", reason, strerror(errno));
19 #define COLD __attribute__((cold))
26 #if HAVE_ATTRIBUTE_NORETURN
28 * NORETURN - a function does not return
30 * Used to mark a function which exits; useful for suppressing warnings.
33 * static void NORETURN fail(const char *reason)
35 * fprintf(stderr, "Error: %s (%s)\n", reason, strerror(errno));
39 #define NORETURN __attribute__((noreturn))
46 #if HAVE_ATTRIBUTE_PRINTF
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.
52 * This allows the compiler to check your parameters as it does for printf().
55 * void PRINTF_FMT(2,3) my_printf(const char *prefix, const char *fmt, ...);
57 #define PRINTF_FMT(nfmt, narg) \
58 __attribute__((format(__printf__, nfmt, narg)))
60 #define PRINTF_FMT(nfmt, narg)
65 #if HAVE_ATTRIBUTE_CONST
67 * IDEMPOTENT - a function's return depends only on its argument
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.
73 #define IDEMPOTENT __attribute__((const))
79 #if HAVE_ATTRIBUTE_UNUSED
82 * UNNEEDED - a variable/function may not be needed
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.
88 * // With some preprocessor options, this is unnecessary.
89 * static UNNEEDED int counter;
91 * // With some preprocessor options, this is unnecessary.
92 * static UNNEEDED void add_to_counter(int add)
97 #define UNNEEDED __attribute__((unused))
101 #if HAVE_ATTRIBUTE_USED
103 * NEEDED - a variable/function is needed
105 * This suppresses warnings about unused variables or functions, but tells
106 * the compiler that it must exist even if it (seems) unused.
109 * // Even if this is unused, these are vital for debugging.
110 * static NEEDED int counter;
111 * static NEEDED void dump_counter(void)
113 * printf("Counter is %i\n", counter);
116 #define NEEDED __attribute__((used))
118 /* Before used, unused functions and vars were always emitted. */
119 #define NEEDED __attribute__((unused))
125 * UNUSED - a parameter is unused
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.
132 * // This is used as a callback, so needs to have this prototype.
133 * static int some_callback(void *unused UNUSED)
138 #define UNUSED __attribute__((unused))
152 #ifndef IS_COMPILE_CONSTANT
153 #if HAVE_BUILTIN_CONSTANT_P
155 * IS_COMPILE_CONSTANT - does the compiler know the value of this expression?
156 * @expr: the expression to evaluate
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.
163 * This can be done using the IS_COMPILE_CONSTANT() macro.
166 * enum greek { ALPHA, BETA, GAMMA, DELTA, EPSILON };
168 * // Out-of-line version.
169 * const char *greek_name(enum greek greek);
172 * static inline const char *_greek_name(enum greek 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**";
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))
189 #define IS_COMPILE_CONSTANT(expr) __builtin_constant_p(expr)
191 /* If we don't know, assume it's not. */
192 #define IS_COMPILE_CONSTANT(expr) 0
196 #ifndef WARN_UNUSED_RESULT
197 #if HAVE_WARN_UNUSED_RESULT
199 * WARN_UNUSED_RESULT - warn if a function return value is unused.
201 * Used to mark a function where it is extremely unlikely that the caller
202 * can ignore the result, eg realloc().
205 * // buf param may be freed by this; need return value!
206 * static char *WARN_UNUSED_RESULT enlarge(char *buf, unsigned *size)
208 * return realloc(buf, (*size) *= 2);
211 #define WARN_UNUSED_RESULT __attribute__((warn_unused_result))
213 #define WARN_UNUSED_RESULT
216 #endif /* CCAN_COMPILER_H */