compiler: don't override existing definitions.
[ccan] / 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 IDEMPOTENT
65 #if HAVE_ATTRIBUTE_CONST
66 /**
67  * IDEMPOTENT - 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 IDEMPOTENT __attribute__((const))
74 #else
75 #define IDEMPOTENT
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 */