Relicense all public domain modules to CC0.
[ccan] / 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 */