BRL-CAD
common.h
Go to the documentation of this file.
1 /* C O M M O N . H
2  * BRL-CAD
3  *
4  * Copyright (c) 2004-2014 United States Government as represented by
5  * the U.S. Army Research Laboratory.
6  *
7  * This library is free software; you can redistribute it and/or
8  * modify it under the terms of the GNU Lesser General Public License
9  * version 2.1 as published by the Free Software Foundation.
10  *
11  * This library is distributed in the hope that it will be useful, but
12  * WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14  * Lesser General Public License for more details.
15  *
16  * You should have received a copy of the GNU Lesser General Public
17  * License along with this file; see the file named COPYING for more
18  * information.
19  */
20 /** @addtogroup fixme */
21 /** @{ */
22 /** @file common.h
23  *
24  * @brief
25  * Header file for the BRL-CAD common definitions.
26  *
27  * This header wraps the system-specific encapsulation of
28  * brlcad_config.h and removes need to conditionally include
29  * brlcad_config.h everywhere based on HAVE_CONFIG_H. The common
30  * definitions are symbols common to the platform being built that
31  * are either detected via configure or hand crafted, as is the case
32  * for the win32 platform.
33  *
34  */
35 
36 #ifndef COMMON_H
37 #define COMMON_H
38 
39 /* include the venerable config.h file. use a pregenerated one for
40  * windows when we cannot autogenerate it easily. do not include
41  * config.h if this file has been installed. (public header files
42  * should not use config defines)
43  */
44 #if defined(BRLCADBUILD) && defined(HAVE_CONFIG_H)
45 
46 # if defined(_WIN32) && !defined(__CYGWIN__) && !defined(CMAKE_HEADERS)
47 # include "config_win.h"
48 # else
49 # include "brlcad_config.h"
50 # endif /* _WIN32 */
51 
52 /* Simulates drand48() functionality using rand() which is assumed to
53  * exist everywhere. The range is [0, 1).
54  */
55 # ifndef HAVE_DRAND48
56 # define drand48() ((double)rand() / (double)(RAND_MAX + 1))
57 # define HAVE_DRAND48 1
58 # define srand48(seed) (srand(seed))
59 # endif
60 
61 # if !defined(__cplusplus) && !defined(HAVE_LRINT) && defined(HAVE_WORKING_LRINT_MACRO)
62 # define lrint(_x) ((long int)(((_x)<0)?(_x)-0.5:(_x)+0.5))
63 # define HAVE_LRINT 1
64 # endif
65 
66 #endif /* BRLCADBUILD & HAVE_CONFIG_H */
67 
68 /* provide declaration markers for header externals */
69 #ifdef __cplusplus
70 # define __BEGIN_DECLS extern "C" {
71 # define __END_DECLS }
72 #else
73 # define __BEGIN_DECLS
74 # define __END_DECLS
75 #endif
76 
77 /* Functions local to one file IN A LIBRARY should be declared HIDDEN.
78  * Disabling the static classifier is sometimes helpful for debugging.
79  * It can help prevent some compilers from inlining functions that one
80  * might want to set a breakpoint on. Do not use on variables.
81  */
82 #if !defined(HIDDEN)
83 # if defined(NDEBUG)
84 # define HIDDEN static
85 # else
86 # define HIDDEN /***/
87 # endif
88 #endif
89 
90 /* ansi c89 does not allow the 'inline' keyword, check if GNU inline
91  * rules are in effect.
92  *
93  * TODO: test removal of __STRICT_ANSI__ on Windows.
94  */
95 #if !defined __cplusplus && (defined(__STRICT_ANSI__) || defined(__GNUC_GNU_INLINE__))
96 # ifndef inline
97 # define inline /***/
98 # endif
99 #endif
100 
101 #ifndef FMAX
102 # define FMAX(a, b) (((a)>(b))?(a):(b))
103 #endif
104 #ifndef FMIN
105 # define FMIN(a, b) (((a)<(b))?(a):(b))
106 #endif
107 
108 /* C99 does not provide a ssize_t even though it is provided by SUS97.
109  * regardless, we use it so make sure it's declared by using the
110  * similar POSIX ptrdiff_t type.
111  */
112 #ifndef HAVE_SSIZE_T
113 # ifdef HAVE_SYS_TYPES_H
114 # include <sys/types.h>
115 # endif
116 # include <limits.h>
117 # include <stddef.h>
118 # ifndef SSIZE_MAX
119 typedef ptrdiff_t ssize_t;
120 # define HAVE_SSIZE_T 1
121 # endif
122 #endif
123 
124 /* make sure most of the C99 stdint types are provided including the
125  * optional uintptr_t type.
126  */
127 #if !defined(INT8_MAX) || !defined(INT16_MAX) || !defined(INT32_MAX) || !defined(INT64_MAX)
128 # if (defined _MSC_VER && (_MSC_VER <= 1500))
129  /* Older Versions of Visual C++ seem to need pstdint.h
130  * but still pass the tests below, so force it based on
131  * version (ugh.) */
132 # include "pstdint.h"
133 # elif defined(__STDC__) || defined(__STRICT_ANSI__) || defined(__SIZE_TYPE__) || defined(HAVE_STDINT_H)
134 # define __STDC_LIMIT_MACROS 1
135 # define __STDC_CONSTANT_MACROS 1
136 # include <stdint.h>
137 # else
138 # include "pstdint.h"
139 # endif
140 #endif
141 
142 /* Provide a means to conveniently test the version of the GNU
143  * compiler. Use it like this:
144  *
145  * #if GCC_PREREQ(2,8)
146  * ... code requiring gcc 2.8 or later ...
147  * #endif
148  *
149  * WARNING: THIS MACRO IS CONSIDERED PRIVATE AND SHOULD NOT BE USED
150  * OUTSIDE OF THIS HEADER FILE. DO NOT RELY ON IT.
151  */
152 #ifdef GCC_PREREQ
153 # warning "GCC_PREREQ unexpectedly defined. Ensure common.h is included first."
154 # undef GCC_PREREQ
155 #endif
156 #if defined __GNUC__
157 # define GCC_PREREQ(major, minor) __GNUC__ > (major) || (__GNUC__ == (major) && __GNUC_MINOR__ >= (minor))
158 #else
159 # define GCC_PREREQ(major, minor) 0
160 #endif
161 
162 /* Provide a means to conveniently test the version of the Intel
163  * compiler. Use it like this:
164  *
165  * #if ICC_PREREQ(800)
166  * ... code requiring icc 8.0 or later ...
167  * #endif
168  *
169  * WARNING: THIS MACRO IS CONSIDERED PRIVATE AND SHOULD NOT BE USED
170  * OUTSIDE OF THIS HEADER FILE. DO NOT RELY ON IT.
171  */
172 /* provide a means to conveniently test the version of ICC */
173 #ifdef ICC_PREREQ
174 # warning "ICC_PREREQ unexpectedly defined. Ensure common.h is included first."
175 # undef ICC_PREREQ
176 #endif
177 #if defined __INTEL_COMPILER
178 # define ICC_PREREQ(version) (__INTEL_COMPILER >= (version))
179 #else
180 # define ICC_PREREQ(version) 0
181 #endif
182 
183 /* This is so we can use gcc's "format string vs arguments"-check for
184  * various printf-like functions, and still maintain compatibility.
185  */
186 #ifndef __attribute__
187 /* This feature is only available in gcc versions 2.5 and later. */
188 # if !GCC_PREREQ(2, 5)
189 # define __attribute__(ignore) /* empty */
190 # endif
191 /* The __-protected variants of `format' and `printf' attributes
192  * are accepted by gcc versions 2.6.4 (effectively 2.7) and later.
193  */
194 # if !GCC_PREREQ(2, 7)
195 # define __format__ format
196 # define __printf__ printf
197 # define __noreturn__ noreturn
198 # endif
199 #endif
200 
201 /* gcc 3.4 doesn't seem to support always_inline with -O0 (yet -Os
202  * reportedly works), so turn it off.
203  */
204 #if !GCC_PREREQ(3, 5)
205 # define always_inline noinline
206 #endif
207 
208 /**
209  * UNUSED provides a common mechanism for declaring unused parameters.
210  * Use it like this:
211  *
212  * int
213  * my_function(int argc, char **UNUSED(argv))
214  * {
215  * ...
216  * }
217  *
218  */
219 #ifdef UNUSED
220 # warning "UNUSED unexpectedly defined. Ensure common.h is included first."
221 # undef UNUSED
222 #endif
223 #if GCC_PREREQ(2, 5)
224  /* GCC-style */
225 # define UNUSED(parameter) UNUSED_ ## parameter __attribute__((unused))
226 #else
227  /* MSVC/C++ */
228 # ifdef __cplusplus
229 # if defined(NDEBUG)
230 # define UNUSED(parameter) /* parameter */
231 # else /* some of them are asserted */
232 # define UNUSED(parameter) (parameter)
233 # endif
234 # else
235 # if defined(_MSC_VER)
236  /* disable reporting an "unreferenced formal parameter" */
237 # pragma warning( disable : 4100 )
238 # endif
239 # define UNUSED(parameter) (parameter)
240 # endif
241 #endif
242 
243 /**
244  * LIKELY provides a common mechanism for providing branch prediction
245  * hints to the compiler so that it can better optimize. It should be
246  * used when it's exceptionally likely that an expected code path will
247  * almost always be executed. Use it like this:
248  *
249  * if (LIKELY(x == 1)) {
250  * ... expected code path ...
251  * }
252  *
253  */
254 #ifdef LIKELY
255 # undef LIKELY
256 # warning "LIKELY unexpectedly defined. Ensure common.h is included first."
257 #endif
258 #if GCC_PREREQ(3, 0) || ICC_PREREQ(800)
259 # define LIKELY(expression) __builtin_expect((expression), 1)
260 #else
261 # define LIKELY(expression) (expression)
262 #endif
263 
264 /**
265  * UNLIKELY provides a common mechanism for providing branch
266  * prediction hints to the compiler so that it can better optimize.
267  * It should be used when it's exceptionally unlikely that a given code
268  * path will ever be executed. Use it like this:
269  *
270  * if (UNLIKELY(x == 0)) {
271  * ... unexpected code path ...
272  * }
273  *
274  */
275 #ifdef UNLIKELY
276 # undef UNLIKELY
277 # warning "UNLIKELY unexpectedly defined. Ensure common.h is included first."
278 #endif
279 #if GCC_PREREQ(3, 0) || ICC_PREREQ(800)
280 # define UNLIKELY(expression) __builtin_expect((expression), 0)
281 #else
282 # define UNLIKELY(expression) (expression)
283 #endif
284 
285 /**
286  * DEPRECATED provides a common mechanism for denoting public API
287  * (e.g., functions, typedefs, variables) that is considered
288  * deprecated. Use it like this:
289  *
290  * DEPRECATED int my_function(void);
291  *
292  * typedef struct karma some_type DEPRECATED;
293  */
294 #ifdef DEPRECATED
295 # undef DEPRECATED
296 # warning "DEPRECATED unexpectedly defined. Ensure common.h is included first."
297 #endif
298 #if GCC_PREREQ(3, 1) || ICC_PREREQ(800)
299 # define DEPRECATED __attribute__((deprecated))
300 #elif defined(_WIN32)
301 # define DEPRECATED __declspec(deprecated("This function is DEPRECATED. Please update code to new API."))
302 #else
303 # define DEPRECATED /* deprecated */
304 #endif
305 
306 /* ActiveState Tcl doesn't include this catch in tclPlatDecls.h, so we
307  * have to add it for them
308  */
309 #if defined(_MSC_VER) && defined(__STDC__)
310  #include <tchar.h>
311  /* MSVC++ misses this. */
312  typedef _TCHAR TCHAR;
313 #endif
314 
315 /* Avoid -Wundef warnings for system headers that use __STDC_VERSION__ without
316  * checking if it's defined.
317  */
318 #if !defined(__STDC_VERSION__)
319 # define __STDC_VERSION__ 0
320 #endif
321 
322 /* Provide macros to indicate availability of diagnostic pragmas for
323  * GCC and Clang.
324  */
325 #define HAVE_GCC_DIAG_PRAGMAS \
326  (defined(__GNUC__) && (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 6)) && !defined(__clang__))
327 
328 #define HAVE_CLANG_DIAG_PRAGMAS \
329  (defined(__clang__) && (__clang_major__ > 2 || (__clang_major__ == 2 && __clang_minor__ >= 8)))
330 
331 
332 /**
333  * Provide a macro for different treatment of initialized extern const
334  * variables between C and C++. In C the following initialization
335  * (definition) is acceptable for external linkage:
336  *
337  * const int var = 10;
338  *
339  * but in C++ const is implicitly internal linkage so it must have
340  * extern qualifier:
341  *
342  * extern const int var = 10;
343  */
344 #if defined(__cplusplus)
345  #define EXTERNVARINIT extern
346 #else
347  #define EXTERNVARINIT
348 #endif
349 
350 #endif /* COMMON_H */
351 /** @} */
352 /*
353  * Local Variables:
354  * mode: C
355  * tab-width: 8
356  * indent-tabs-mode: t
357  * c-file-style: "stroustrup"
358  * End:
359  * ex: shiftwidth=4 tabstop=8
360  */
ptrdiff_t ssize_t
Definition: common.h:119
#define TCHAR
Definition: vlist.c:486