| blob | fcb89c8f2a68a9aa90f5cba4746a98910c0a551d |
1 #ifndef CCAN_COMPILER_H
2 #define CCAN_COMPILER_H
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
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
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
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
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
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
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
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
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