The Random123 library is portable across C, C++, CUDA, OpenCL environments, and multiple operating systems (Linux, Windows 7, Mac OS X, FreeBSD, Solaris). This level of portability requires the abstraction of some features and idioms that are either not standardized (e.g., asm statments), or for which different vendors have their own standards (e.g., SSE intrinsics) or for which vendors simply refuse to conform to well-established standards (e.g., <inttypes.h>).
Random123/features/compilerfeatures.h conditionally includes a compiler-or-OS-specific Random123/featires/XXXfeatures.h file which defines appropriate values for the preprocessor symbols which can be used with a specific compiler or OS. Those symbols will then be used by other header files and source files in the Random123 library (and may be used by applications) to control what actually gets presented to the compiler.
Most of the symbols are boolean valued. In general, they will always be defined with value either 1 or 0, so do NOT use #ifdef. Use #if R123_USE_SOMETHING instead.
Library users can override any value by defining the pp-symbol with a compiler option, e.g.,
cc -DR123_USE_MULHILO64_C99
will use a strictly c99 version of the full-width 64x64->128-bit multiplication function, even if it would be disabled by default.
All boolean-valued pre-processor symbols in Random123/features/compilerfeatures.h start with the prefix R123_USE_
AES_NI
AES_OPENSSL
SSE4_2
SSE4_1
SSE
STD_RANDOM
GNU_UINT128
ASM_GNU
ASM_MSASM
CPUID_MSVC
CXX0X
X86INTRIN_H
IA32INTRIN_H
EMMINTRIN_H
SMMINTRIN_H
WMMINTRIN_H
INTRIN_H
MULHILO32_ASM
MULHILO64_ASM
MULHILO64_MSVC_INTRIN
MULHILO64_CUDA_INTRIN
MULHILO64_OPENCL_INTRIN
MULHILO64_C99
Most have obvious meanings. Some non-obvious ones:
AES_NI and AES_OPENSSL are not mutually exclusive. You can have one, both or neither.
GNU_UINT128 says that it's safe to use __uint128_t, but it does not require its use. In particular, it should be used in mulhilo<uint64_t> only if MULHILO64_ASM is unset.
If the XXXINTRIN_H macros are true, then one should
#include <xxxintrin.h>
to gain accesss to compiler intrinsics.
R123_USE_CXX0X says that C++0x features are available. It is therefore safe to use things like static_assert and defaulted and deleted constructors. Specific C++0x features, e.g., <random> may be under the control of other macros.
There are a number of invariants that are always true. Application code may choose to rely on these:
There are also non-boolean valued symbols:
R123_STATIC_INLINE - According to both C99 and GNU99, the 'static inline' declaration allows the compiler to not emit code if the function is not used. Note that the semantics of 'inline', 'static' and 'extern' in gcc have changed over time and are subject to modification by command line options, e.g., -std=gnu89, -fgnu-inline. Nevertheless, it appears that the meaning of 'static inline' has not changed over time and (with a little luck) the use of 'static inline' here will be portable between versions of gcc and to other C99 compilers. See: http://gcc.gnu.org/onlinedocs/gcc/Inline.html http://www.greenend.org.uk/rjk/2003/03/inline.html
R123_FORCE_INLINE(decl) - which expands to 'decl', adorned with the compiler-specific embellishments to strongly encourage that the declared function be inlined. If there is no such compiler-specific magic, it should expand to decl, unadorned.
R123_CUDA_DEVICE - which expands to __device__ (or something else with sufficiently similar semantics) when CUDA is in use, and expands to nothing in other cases.
R123_ASSERT(x) - which expands to assert(x), or maybe to nothing at all if we're in an environment so feature-poor that you can't even call assert (I'm looking at you, CUDA and OpenCL), or even include assert.h safely (OpenCL).
R123_ULONG_LONG - which expands to a declaration of the longest available unsigned integer.
R123_64BIT(x) - expands to something equivalent to UINT64_C(x) from <stdint.h>, even in environments where <stdint.h> is not available, e.g., MSVC and OpenCL.
1.7.1