BRL-CAD
defines.h
Go to the documentation of this file.
1 /* D E F I N E S . 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 
21 /** @file bu/defines.h
22  *
23  * Commonly used definitions for the BRL-CAD Utility Library, LIBBU.
24  *
25  * The two letters "BU" stand for "BRL-CAD" and "Utility". This
26  * library provides several layers of low-level utility routines,
27  * providing features that make cross-platform coding easier.
28  *
29  * Parallel processing support: threads, semaphores, parallel-malloc.
30  * Consolidated logging support: bu_log(), bu_exit(), and bu_bomb().
31  *
32  * The intention is that these routines are general extensions to the
33  * data types offered by the C language itself, and to the basic C
34  * runtime support provided by the system LIBC. All routines in LIBBU
35  * are designed to be "parallel-safe" (sometimes called "mp-safe" or
36  * "thread-safe" if parallelism is via threading) to greatly ease code
37  * development for multiprocessor systems.
38  *
39  * All of the data types provided by this library are defined in bu.h;
40  * none of the routines in this library will depend on data types
41  * defined in other BRL-CAD header files, such as vmath.h. Look for
42  * those routines in LIBBN.
43  *
44  * All truly fatal errors detected by the library use bu_bomb() to
45  * exit with a status of 12. The LIBBU variants of system calls
46  * (e.g., bu_malloc()) do not return to the caller (unless there's a
47  * bomb hook defined) unless they succeed, thus sparing the programmer
48  * from constantly having to check for NULL return codes.
49  *
50  */
51 #ifndef BU_DEFINES_H
52 #define BU_DEFINES_H
53 
54 #include "common.h"
55 #include <stddef.h>
56 #include <sys/types.h>
57 
58 #ifndef BU_EXPORT
59 # if defined(BU_DLL_EXPORTS) && defined(BU_DLL_IMPORTS)
60 # error "Only BU_DLL_EXPORTS or BU_DLL_IMPORTS can be defined, not both."
61 # elif defined(BU_DLL_EXPORTS)
62 # define BU_EXPORT __declspec(dllexport)
63 # elif defined(BU_DLL_IMPORTS)
64 # define BU_EXPORT __declspec(dllimport)
65 # else
66 # define BU_EXPORT
67 # endif
68 #endif
69 
70 /* NOTE: do not rely on these values */
71 #define BRLCAD_OK 0
72 #define BRLCAD_ERROR 1
73 
74  /**
75  * BU_IGNORE provides a common mechanism for innocuously ignoring a
76  * parameter that is sometimes used and sometimes not. It should
77  * "practically" result in nothing of concern happening. It's
78  * commonly used by macros that disable functionality based on
79  * compilation settings (e.g., BU_ASSERT()) and shouldn't normally
80  * need to be used directly by code.
81  */
82 #define BU_IGNORE(_parm) (void)(_parm)
83 
84 /**
85  * @def BU_DIR_SEPARATOR
86  * the default directory separator character
87  */
88 #ifdef DIR_SEPARATOR
89 # define BU_DIR_SEPARATOR DIR_SEPARATOR
90 #else
91 # ifdef DIR_SEPARATOR_2
92 # define BU_DIR_SEPARATOR DIR_SEPARATOR_2
93 # else
94 # ifdef _WIN32
95 # define BU_DIR_SEPARATOR '\\'
96 # else
97 # define BU_DIR_SEPARATOR '/'
98 # endif /* _WIN32 */
99 # endif /* DIR_SEPARATOR_2 */
100 #endif /* DIR_SEPARATOR */
101 
102 /**
103  * Maximum length of a filesystem path. Typically defined in a system
104  * file but if it isn't set, we create it.
105  */
106 #ifndef MAXPATHLEN
107 # ifdef PATH_MAX
108 # define MAXPATHLEN PATH_MAX
109 # else
110 # ifdef _MAX_PATH
111 # define MAXPATHLEN _MAX_PATH
112 # else
113 # define MAXPATHLEN 1024
114 # endif
115 # endif
116 #endif
117 
118 /**
119  * set to the path list separator character
120  */
121 #if defined(PATH_SEPARATOR)
122 # define BU_PATH_SEPARATOR PATH_SEPARATOR
123 #else
124 # if defined(_WIN32)
125 # define BU_PATH_SEPARATOR ';'
126 # else
127 # define BU_PATH_SEPARATOR ':'
128 # endif /* _WIN32 */
129 #endif /* PATH_SEPARATOR */
130 
131 
132 /**
133  * @def BU_FLSTR
134  *
135  * Macro for getting a concatenated string of the current file and
136  * line number. Produces something of the form: "filename.c"":""1234"
137  */
138 #define bu_cpp_str(s) # s
139 #define bu_cpp_xstr(s) bu_cpp_str(s)
140 #define bu_cpp_glue(a, b) a ## b
141 #define bu_cpp_xglue(a, b) bu_cpp_glue(a, b)
142 #define BU_FLSTR __FILE__ ":" bu_cpp_xstr(__LINE__)
143 
144 
145 /**
146  * shorthand declaration of a printf-style functions
147  */
148 #if !defined(_BU_ATTR_PRINTF12)
149 #define _BU_ATTR_PRINTF12 __attribute__ ((__format__ (__printf__, 1, 2)))
150 #endif
151 #if !defined(_BU_ATTR_PRINTF23)
152 #define _BU_ATTR_PRINTF23 __attribute__ ((__format__ (__printf__, 2, 3)))
153 #endif
154 #if !defined(_BU_ATTR_SCANF23)
155 #define _BU_ATTR_SCANF23 __attribute__ ((__format__ (__scanf__, 2, 3)))
156 #endif
157 
158 /**
159  * shorthand declaration of a function that doesn't return
160  */
161 #define _BU_ATTR_NORETURN __attribute__ ((__noreturn__))
162 
163 /**
164  * shorthand declaration of a function that should always be inline
165  */
166 #define _BU_ATTR_ALWAYS_INLINE __attribute__ ((always_inline))
167 
168 /**
169  * If we're compiling strict, turn off "format string vs arguments"
170  * checks - BRL-CAD customizes the arguments to some of these
171  * function types (adding bu_vls support) and that is a problem with
172  * strict checking.
173  */
174 #if defined(STRICT_FLAGS)
175 # undef _BU_ATTR_PRINTF12
176 # undef _BU_ATTR_PRINTF23
177 # undef _BU_ATTR_SCANF23
178 # undef _BU_ATTR_NORETURN
179 # define _BU_ATTR_PRINTF12
180 # define _BU_ATTR_PRINTF23
181 # define _BU_ATTR_SCANF23
182 # define _BU_ATTR_NORETURN
183 #endif
184 
185 /**
186  * This macro is used to take the 'C' function name, and convert it at
187  * compile time to the FORTRAN calling convention.
188  *
189  * Lower case, with a trailing underscore.
190  */
191 #define BU_FORTRAN(lc, uc) lc ## _
192 
193 
194 /**
195  * @def BU_ASSERT(eqn)
196  * Quick and easy macros to generate an informative error message and
197  * abort execution if the specified condition does not hold true.
198  *
199  * @def BU_ASSERT_PTR(eqn)
200  * Quick and easy macros to generate an informative error message and
201  * abort execution if the specified condition does not hold true.
202  *
203  * @def BU_ASSERT_LONG(eqn)
204  * Quick and easy macros to generate an informative error message and
205  * abort execution if the specified condition does not hold true.
206  *
207  * @def BU_ASSERT_DOUBLE(eqn)
208  * Quick and easy macros to generate an informative error message and
209  * abort execution if the specified condition does not hold true.
210  *
211  * Example: BU_ASSERT_LONG(j+7, <, 42);
212  */
213 #ifdef NO_BOMBING_MACROS
214 # define BU_ASSERT(_equation) BU_IGNORE((_equation))
215 #else
216 # define BU_ASSERT(_equation) \
217  if (UNLIKELY(!(_equation))) { \
218  bu_log("BU_ASSERT(" #_equation ") failed, file %s, line %d\n", \
219  __FILE__, __LINE__); \
220  bu_bomb("BU_ASSERT failure\n"); \
221  }
222 #endif
223 
224 #ifdef NO_BOMBING_MACROS
225 # define BU_ASSERT_PTR(_lhs, _relation, _rhs) BU_IGNORE((_lhs)); BU_IGNORE((_rhs))
226 #else
227 # define BU_ASSERT_PTR(_lhs, _relation, _rhs) \
228  if (UNLIKELY(!((_lhs) _relation (_rhs)))) { \
229  bu_log("BU_ASSERT_PTR(" #_lhs #_relation #_rhs ") failed, lhs=%p, rhs=%p, file %s, line %d\n", \
230  (void *)(_lhs), (void *)(_rhs), \
231  __FILE__, __LINE__); \
232  bu_bomb("BU_ASSERT_PTR failure\n"); \
233  }
234 #endif
235 
236 
237 #ifdef NO_BOMBING_MACROS
238 # define BU_ASSERT_LONG(_lhs, _relation, _rhs) BU_IGNORE((_lhs)); BU_IGNORE((_rhs))
239 #else
240 # define BU_ASSERT_LONG(_lhs, _relation, _rhs) \
241  if (UNLIKELY(!((_lhs) _relation (_rhs)))) { \
242  bu_log("BU_ASSERT_LONG(" #_lhs #_relation #_rhs ") failed, lhs=%ld, rhs=%ld, file %s, line %d\n", \
243  (long)(_lhs), (long)(_rhs), \
244  __FILE__, __LINE__); \
245  bu_bomb("BU_ASSERT_LONG failure\n"); \
246  }
247 #endif
248 
249 
250 #ifdef NO_BOMBING_MACROS
251 # define BU_ASSERT_SIZE_T(_lhs, _relation, _rhs) BU_IGNORE((_lhs)); BU_IGNORE((_rhs))
252 #else
253 # define BU_ASSERT_SIZE_T(_lhs, _relation, _rhs) \
254  if (UNLIKELY(!((_lhs) _relation (_rhs)))) { \
255  bu_log("BU_ASSERT_SIZE_T(" #_lhs #_relation #_rhs ") failed, lhs=%zd, rhs=%zd, file %s, line %d\n", \
256  (size_t)(_lhs), (size_t)(_rhs), \
257  __FILE__, __LINE__); \
258  bu_bomb("BU_ASSERT_SIZE_T failure\n"); \
259  }
260 #endif
261 
262 
263 #ifdef NO_BOMBING_MACROS
264 # define BU_ASSERT_SSIZE_T(_lhs, _relation, _rhs) BU_IGNORE((_lhs)); BU_IGNORE((_rhs))
265 #else
266 # define BU_ASSERT_SSIZE_T(_lhs, _relation, _rhs) \
267  if (UNLIKELY(!((_lhs) _relation (_rhs)))) { \
268  bu_log("BU_ASSERT_SSIZE_T(" #_lhs #_relation #_rhs ") failed, lhs=%zd, rhs=%zd, file %s, line %d\n", \
269  (ssize_t)(_lhs), (ssize_t)(_rhs), \
270  __FILE__, __LINE__); \
271  bu_bomb("BU_ASSERT_SSIZE_T failure\n"); \
272  }
273 #endif
274 
275 
276 #ifdef NO_BOMBING_MACROS
277 # define BU_ASSERT_DOUBLE(_lhs, _relation, _rhs) BU_IGNORE((_lhs)); BU_IGNORE((_rhs))
278 #else
279 # define BU_ASSERT_DOUBLE(_lhs, _relation, _rhs) \
280  if (UNLIKELY(!((_lhs) _relation (_rhs)))) { \
281  bu_log("BU_ASSERT_DOUBLE(" #_lhs #_relation #_rhs ") failed, lhs=%lf, rhs=%lf, file %s, line %d\n", \
282  (double)(_lhs), (double)(_rhs), \
283  __FILE__, __LINE__); \
284  bu_bomb("BU_ASSERT_DOUBLE failure\n"); \
285  }
286 #endif
287 
288 /**
289  * fastf_t - Intended to be the fastest floating point data type on
290  * the current machine, with at least 64 bits of precision. On 16 and
291  * 32 bit machines, this is typically "double", but on 64 bit machines,
292  * it is often "float". Virtually all floating point variables (and
293  * more complicated data types, like vect_t and mat_t) are defined as
294  * fastf_t. The one exception is when a subroutine return is a
295  * floating point value; that is always declared as "double".
296  *
297  * TODO: If used pervasively, it should eventually be possible to make
298  * fastf_t a GMP C++ type for fixed-precision computations.
299  */
300 typedef double fastf_t;
301 
302 /**
303  * Definitions about limits of floating point representation
304  * Eventually, should be tied to type of hardware (IEEE, IBM, Cray)
305  * used to implement the fastf_t type.
306  *
307  * MAX_FASTF - Very close to the largest value that can be held by a
308  * fastf_t without overflow. Typically specified as an integer power
309  * of ten, to make the value easy to spot when printed. TODO: macro
310  * function syntax instead of constant (DEPRECATED)
311  *
312  * SQRT_MAX_FASTF - sqrt(MAX_FASTF), or slightly smaller. Any number
313  * larger than this, if squared, can be expected to * produce an
314  * overflow. TODO: macro function syntax instead of constant
315  * (DEPRECATED)
316  *
317  * SMALL_FASTF - Very close to the smallest value that can be
318  * represented while still being greater than zero. Any number
319  * smaller than this (and non-negative) can be considered to be
320  * zero; dividing by such a number can be expected to produce a
321  * divide-by-zero error. All divisors should be checked against
322  * this value before actual division is performed. TODO: macro
323  * function syntax instead of constant (DEPRECATED)
324  *
325  * SQRT_SMALL_FASTF - sqrt(SMALL_FASTF), or slightly larger. The
326  * value of this is quite a lot larger than that of SMALL_FASTF. Any
327  * number smaller than this, when squared, can be expected to produce
328  * a zero result. TODO: macro function syntax instead of constant
329  * (DEPRECATED)
330  *
331  */
332 #if defined(vax)
333 /* DEC VAX "D" format, the most restrictive */
334 # define MAX_FASTF 1.0e37 /* Very close to the largest number */
335 # define SQRT_MAX_FASTF 1.0e18 /* This squared just avoids overflow */
336 # define SMALL_FASTF 1.0e-37 /* Anything smaller is zero */
337 # define SQRT_SMALL_FASTF 1.0e-18 /* This squared gives zero */
338 #else
339 /* IBM format, being the next most restrictive format */
340 # define MAX_FASTF 1.0e73 /* Very close to the largest number */
341 # define SQRT_MAX_FASTF 1.0e36 /* This squared just avoids overflow */
342 # define SMALL_FASTF 1.0e-77 /* Anything smaller is zero */
343 # if defined(aux)
344 # define SQRT_SMALL_FASTF 1.0e-40 /* _doprnt error in libc */
345 # else
346 # define SQRT_SMALL_FASTF 1.0e-39 /* This squared gives zero */
347 # endif
348 #endif
349 
350 /** DEPRECATED, do not use */
351 #define SMALL SQRT_SMALL_FASTF
352 
353 
354 #endif /* BU_DEFINES_H */
355 
356 /*
357  * Local Variables:
358  * mode: C
359  * tab-width: 8
360  * indent-tabs-mode: t
361  * c-file-style: "stroustrup"
362  * End:
363  * ex: shiftwidth=4 tabstop=8
364  */
Header file for the BRL-CAD common definitions.
double fastf_t
Definition: defines.h:300