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