- Generated on Tue Mar 7 2023 23:41:52 for BRL-CAD by
1.9.3
|
BRL-CAD
|
Files | |
| file | common.h |
| Header file for the BRL-CAD common definitions. | |
Macros | |
| #define | FMAX(a, b) (((a)>(b))?(a):(b)) |
| #define | FMIN(a, b) (((a)<(b))?(a):(b)) |
| #define | _FILE_OFFSET_BITS 64 |
| #define | b_off_t off_t |
| #define | MAXPATHLEN 2048 |
| #define | GCC_PREREQ(major, minor) 0 |
| #define | ICC_PREREQ(version) 0 |
| #define | __attribute__(ignore) /* empty */ |
| #define | __format__ format |
| #define | __printf__ printf |
| #define | __noreturn__ noreturn |
| #define | always_inline noinline |
| #define | UNUSED(parameter) /* parameter */ |
| #define | LIKELY(expression) (expression) |
| #define | UNLIKELY(expression) (expression) |
| #define | DEPRECATED /* deprecated */ |
| #define | NORETURN /* does not return */ |
| #define | FAUX_NORETURN /* pretend does not return */ |
| #define | __STDC_VERSION__ 0 |
| #define | EXTERNVARINIT extern |
| #define | CPP_STR(x) # x |
| #define | CPP_XSTR(x) CPP_STR(x) |
| #define | CPP_GLUE(a, b) a ## b |
| #define | CPP_XGLUE(a, b) CPP_GLUE(a, b) |
| #define | CPP_SCAN(sz) "%" CPP_XSTR(sz) "s" |
| #define | CPP_FILELINE __FILE__ ":" CPP_XSTR(__LINE__) |
| #define | COMPILER_DLLEXPORT |
| #define | COMPILER_DLLIMPORT |
This header wraps system and compilation-specific defines from brlcad_config.h and removes need to conditionally include brlcad_config.h everywhere based on HAVE_CONFIG_H. The common definitions are symbols common to the platform being built that are either detected via configure or hand crafted, as is the case for the win32 platform.
NOTE: In order to use compile-time API, applications need to define BRLCADBUILD and HAVE_CONFIG_H before including this header.
| #define FMAX | ( | a, | |
| b | |||
| ) | (((a)>(b))?(a):(b)) |
| #define FMIN | ( | a, | |
| b | |||
| ) | (((a)<(b))?(a):(b)) |
| #define b_off_t off_t |
| #define MAXPATHLEN 2048 |
| #define GCC_PREREQ | ( | major, | |
| minor | |||
| ) | 0 |
Provide a means to conveniently test the version of the GNU compiler. Use it like this:
WARNING: THIS MACRO IS CONSIDERED PRIVATE AND SHOULD NOT BE USED OUTSIDE OF THIS HEADER FILE. DO NOT RELY ON IT.
| #define ICC_PREREQ | ( | version | ) | 0 |
Provide a means to conveniently test the version of the Intel compiler. Use it like this:
WARNING: THIS MACRO IS CONSIDERED PRIVATE AND SHOULD NOT BE USED OUTSIDE OF THIS HEADER FILE. DO NOT RELY ON IT.
| #define UNUSED | ( | parameter | ) | /* parameter */ |
| #define LIKELY | ( | expression | ) | (expression) |
LIKELY provides a common mechanism for providing branch prediction hints to the compiler so that it can better optimize. It should be used when it's exceptionally likely that an expected code path will almost always be executed. Use it like this:
if (LIKELY(x == 1)) { ... expected code path ... }
| #define UNLIKELY | ( | expression | ) | (expression) |
UNLIKELY provides a common mechanism for providing branch prediction hints to the compiler so that it can better optimize. It should be used when it's exceptionally unlikely that a given code path will ever be executed. Use it like this:
if (UNLIKELY(x == 0)) { ... unexpected code path ... }
| #define DEPRECATED /* deprecated */ |
| #define NORETURN /* does not return */ |
NORETURN declares that a function does not return.
For portability, the attribute must precede the function, i.e., be declared on the left:
NORETURN void function(void);
Note that throwing an exception or calling longjmp() do not constitute a return. Functions that (always) infinite loop can be considered functions that do not return. Functions that do not return should have a void return type. This option is a hint to compilers and static analyers, to reduce false positive reporting.
| #define FAUX_NORETURN /* pretend does not return */ |
FAUX_NORETURN declares a function should be treated as if it does not return, even though it can.
As this label is (currently) Clang-specific, it can be declared on the left or right of a function declaration. Left is recommended for consistency with other annotations, e.g.:
FAUX_NORETURN void function(void);
This annocation is almost identical to NORETURN except that it does not affect code generation and can be used on functions that actually return. It's typically useful for annotating assertion handlers (e.g., assert()) that sometimes return and should not be used on NORETURN functions. This annotation is primarily a hint to static analyzers.
| #define EXTERNVARINIT extern |
globally disable certain warnings. do NOT add new warnings here without discussion and research. only warnings that cannot be quieted without objectively decreasing code quality should be added! even warnings that are innocuous or produce false-positive should be quelled when possible.
any warnings added should include a description and justification. Provide a macro for different treatment of initialized extern const variables between C and C++. In C the following initialization (definition) is acceptable for external linkage:
const int var = 10;
but in C++ const is implicitly internal linkage so it must have extern qualifier:
extern const int var = 10;
Provide canonical preprocessor stringification.
Provide canonical preprocessor expanded stringification.
| #define CPP_GLUE | ( | a, | |
| b | |||
| ) | a ## b |
| #define CPP_XGLUE | ( | a, | |
| b | |||
| ) | CPP_GLUE(a, b) |
| #define CPP_SCAN | ( | sz | ) | "%" CPP_XSTR(sz) "s" |
| #define CPP_FILELINE __FILE__ ":" CPP_XSTR(__LINE__) |
| #define COMPILER_DLLEXPORT |
1.9.3