modules: update documentation examples so they compile under ccanlint.
[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_ATTRIBUTE - 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_ATTRIBUTE moan(const char *reason)
14  * {
15  *      fprintf(stderr, "Error: %s (%s)\n", reason, strerror(errno));
16  * }
17  */
18 #define COLD_ATTRIBUTE __attribute__((cold))
19 #else
20 #define COLD_ATTRIBUTE
21 #endif
22
23 #if HAVE_ATTRIBUTE_PRINTF
24 /**
25  * PRINTF_ATTRIBUTE - 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_ATTRIBUTE(2,3) my_printf(const char *prefix,
33  *                                      const char *fmt, ...);
34  */
35 #define PRINTF_ATTRIBUTE(nfmt, narg) \
36         __attribute__((format(__printf__, nfmt, narg)))
37 #else
38 #define PRINTF_ATTRIBUTE(nfmt, narg)
39 #endif
40
41 #if HAVE_ATTRIBUTE_CONST
42 /**
43  * IDEMPOTENT_ATTRIBUTE - a function's return depends only on its argument
44  *
45  * This allows the compiler to assume that the function will return the exact
46  * same value for the exact same arguments.  This implies that the function
47  * must not use global variables, or dereference pointer arguments.
48  */
49 #define IDEMPOTENT_ATTRIBUTE __attribute__((const))
50 #else
51 #define IDEMPOTENT_ATTRIBUTE
52 #endif
53
54 #if HAVE_ATTRIBUTE_UNUSED
55 /**
56  * UNNEEDED_ATTRIBUTE - a parameter/variable/function may not be needed
57  *
58  * This suppresses warnings about unused variables or parameters, but tells
59  * the compiler that if it is unused it need not emit it into the source code.
60  *
61  * Example:
62  * // With some preprocessor options, this is unnecessary.
63  * static UNNEEDED_ATTRIBUTE int counter;
64  *
65  * // With some preprocessor options, this is unnecessary.
66  * static UNNEEDED_ATTRIBUTE void add_to_counter(int add)
67  * {
68  *      counter += add;
69  * }
70  */
71 #define UNNEEDED_ATTRIBUTE __attribute__((unused))
72
73 #if HAVE_ATTRIBUTE_USED
74 /**
75  * NEEDED_ATTRIBUTE - a parameter/variable/function is needed
76  *
77  * This suppresses warnings about unused variables or parameters, but tells
78  * the compiler that it must exist even if it (seems) unused.
79  *
80  * Example:
81  *      // Even if this is unused, these are vital for debugging.
82  *      static UNNEEDED_ATTRIBUTE int counter;
83  *      static UNNEEDED_ATTRIBUTE void dump_counter(void)
84  *      {
85  *              printf("Counter is %i\n", counter);
86  *      }
87  */
88 #define NEEDED_ATTRIBUTE __attribute__((used))
89 #else
90 /* Before used, unused functions and vars were always emitted. */
91 #define NEEDED_ATTRIBUTE __attribute__((unused))
92 #endif
93 #else
94 #define UNNEEDED_ATTRIBUTE
95 #define NEEDED_ATTRIBUTE
96 #endif
97
98 #if HAVE_BUILTIN_CONSTANT_P
99 /**
100  * IS_COMPILE_CONSTANT - does the compiler know the value of this expression?
101  * @expr: the expression to evaluate
102  *
103  * When an expression manipulation is complicated, it is usually better to
104  * implement it in a function.  However, if the expression being manipulated is
105  * known at compile time, it is better to have the compiler see the entire
106  * expression so it can simply substitute the result.
107  *
108  * This can be done using the IS_COMPILE_CONSTANT() macro.
109  *
110  * Example:
111  *      enum greek { ALPHA, BETA, GAMMA, DELTA, EPSILON };
112  *
113  *      // Out-of-line version.
114  *      const char *greek_name(enum greek greek);
115  *
116  *      // Inline version.
117  *      static inline char *_greek_name(enum greek greek)
118  *      {
119  *              switch (greek) {
120  *              case ALPHA: return "alpha";
121  *              case BETA: return "beta";
122  *              case GAMMA: return "gamma";
123  *              case DELTA: return "delta";
124  *              case EPSILON: return "epsilon";
125  *              default: return "**INVALID**";
126  *              }
127  *      }
128  *
129  *      // Use inline if compiler knows answer.  Otherwise call function
130  *      // to avoid copies of the same code everywhere.
131  *      #define greek_name(g)                                           \
132  *               (IS_COMPILE_CONSTANT(greek) ? _greek_name(g) : greek_name(g))
133  */
134 #define IS_COMPILE_CONSTANT(expr) __builtin_constant_p(expr)
135 #else
136 /* If we don't know, assume it's not. */
137 #define IS_COMPILE_CONSTANT(expr) 0
138 #endif
139 #endif /* CCAN_COMPILER_H */