Language and compiler abstraction macro definitions. More...

#include "corecel/Config.hh"

Macros
#define	CELER_FUNCTION
	Decorate a function that works on both host and device, with and without NVCC. More...

#define	CELER_FORCEINLINE inline

#define	CELER_COMPILER_UNKNOWN 0
	Detection for the current compiler isn't supported yet.

#define	CELER_COMPILER_CLANG 1
	Compiling with clang, or a clang-based compiler defining clang (hipcc)

#define	CELER_COMPILER CELER_COMPILER_UNKNOWN
	Compare to on of the CELER_COMPILER_<compiler> macros to check which compiler is in use. More...

#define	CELER_FORCEINLINE_FUNCTION CELER_FUNCTION CELER_FORCEINLINE
	Like CELER_FUNCTION but forces inlining. More...

#define	CELER_CONSTEXPR_FUNCTION constexpr CELER_FORCEINLINE_FUNCTION
	Decorate a function that works on both host and device, with and without NVCC, can be evaluated at compile time, and should be forcibly inlined.

#define	CELER_UNLIKELY(COND) (COND)
	Mark the result of this condition to be "unlikely". More...

#define	CELER_UNREACHABLE
	Mark a point in code as being impossible to reach in normal execution. More...

#define	CELER_USE_DEVICE 0
	True if HIP or CUDA are enabled, false otherwise.

#define	CELER_DEVICE_SOURCE 0
	Defined and true if building a HIP or CUDA source file. More...

#define	CELER_DEVICE_COMPILE 0
	Defined and true if building device code in HIP or CUDA. More...

#define	CELER_DEVICE_PREFIX(TOK) DEVICE_UNAVAILABLE
	Add a prefix "hip" or "cuda" to a code token.

#define	CELER_TRY_HANDLE(STATEMENT, HANDLE_EXCEPTION)
	"Try" to execute the statement, and "handle" all thrown errors by calling the given function-like error handler with a `std::exception_ptr` object. More...

#define	CELER_TRY_HANDLE_CONTEXT( STATEMENT, HANDLE_EXCEPTION, CONTEXT_EXCEPTION)
	Try the given statement, and if it fails, chain it into the given exception. More...

#define	CELER_DEFAULT_COPY_MOVE(CLS)
	Explicitly declare defaulted copy and move constructors and assignment operators. More...

#define	CELER_DELETE_COPY_MOVE(CLS)
	Explicitly declare deleted copy and move constructors and assignment operators. More...

#define	CELER_DEFAULT_MOVE_DELETE_COPY(CLS)
	Explicitly declare defaulted copy and move constructors and assignment operators. More...

#define	CELER_DISCARD(CODE) static_cast<void>(sizeof(CODE));
	The argument is an unevaluated operand which will generate no code but force the expression to be used. More...

Detailed Description

Language and compiler abstraction macro definitions.

The Macros file defines cross-platform (CUDA, C++, HIP) macros that expand to attributes depending on the compiler and build configuration.

Macro Definition Documentation

◆ CELER_COMPILER

#define CELER_COMPILER CELER_COMPILER_UNKNOWN

Compare to on of the CELER_COMPILER_<compiler> macros to check which compiler is in use.

TODO: add and test more compilers as needed.

◆ CELER_DEFAULT_COPY_MOVE

#define CELER_DEFAULT_COPY_MOVE ( CLS )

Value:

    CLS(CLS const&) = default;            \
    CLS& operator=(CLS const&) = default; \
    CLS(CLS&&) = default;                 \
    CLS& operator=(CLS&&) = default

Explicitly declare defaulted copy and move constructors and assignment operators.

Use this if the destructor is declared explicitly, or as part of the "protected" section of an interface class to prevent assignment between incompatible classes.

◆ CELER_DEFAULT_MOVE_DELETE_COPY

#define CELER_DEFAULT_MOVE_DELETE_COPY ( CLS )

Value:

    CLS(CLS const&) = delete;               \
    CLS& operator=(CLS const&) = delete;    \
    CLS(CLS&&) = default;                   \
    CLS& operator=(CLS&&) = default

Explicitly declare defaulted copy and move constructors and assignment operators.

Use this if the destructor is declared explicitly.

◆ CELER_DELETE_COPY_MOVE

#define CELER_DELETE_COPY_MOVE ( CLS )

Value:

    CLS(CLS const&) = delete;            \
    CLS& operator=(CLS const&) = delete; \
    CLS(CLS&&) = delete;                 \
    CLS& operator=(CLS&&) = delete

Explicitly declare deleted copy and move constructors and assignment operators.

Use this for scoped RAII classes.

◆ CELER_DEVICE_COMPILE

#define CELER_DEVICE_COMPILE 0

Defined and true if building device code in HIP or CUDA.

This is a generic replacement for CUDA_ARCH .

◆ CELER_DEVICE_SOURCE

#define CELER_DEVICE_SOURCE 0

Defined and true if building a HIP or CUDA source file.

This is a generic replacement for CUDACC .

◆ CELER_DISCARD

#define CELER_DISCARD ( CODE ) static_cast<void>(sizeof(CODE));

The argument is an unevaluated operand which will generate no code but force the expression to be used.

This is used in place of the

[[maybe_unused]]

attribute, which actually generates warnings in older versions of GCC.

◆ CELER_FORCEINLINE_FUNCTION

#define CELER_FORCEINLINE_FUNCTION CELER_FUNCTION CELER_FORCEINLINE

Like CELER_FUNCTION but forces inlining.

Compiler optimizers usually can tell what needs optimizing, but this function can provide speedups (and smaller sampling profiles) when inlining optimizations are not enabled. It should be used sparingly.

◆ CELER_FUNCTION

#define CELER_FUNCTION

Decorate a function that works on both host and device, with and without NVCC.

The name of this function and its siblings is based on the Kokkos naming scheme.

◆ CELER_TRY_HANDLE

#define CELER_TRY_HANDLE	(	STATEMENT,
		HANDLE_EXCEPTION
	)

Value:

    do                                                  \
    {                                                   \
        try                                             \
        {                                               \
            STATEMENT;                                  \
        }                                               \
        catch (...)                                     \
        {                                               \
            HANDLE_EXCEPTION(std::current_exception()); \
        }                                               \
    } while (0)

"Try" to execute the statement, and "handle" all thrown errors by calling the given function-like error handler with a std::exception_ptr object.

Note: A file that uses this macro must include the <exception> header (but since the HANDLE_EXCEPTION needs to take an exception pointer, it's got to be included anyway).

◆ CELER_TRY_HANDLE_CONTEXT

#define CELER_TRY_HANDLE_CONTEXT	(	STATEMENT,
		HANDLE_EXCEPTION,
		CONTEXT_EXCEPTION
	)

Value:

    CELER_TRY_HANDLE(                                      \
        do {                                               \
            try                                            \
            {                                              \
                STATEMENT;                                 \
            }                                              \
            catch (...)                                    \
            {                                              \
                std::throw_with_nested(CONTEXT_EXCEPTION); \
            }                                              \
        } while (0),                                       \
        HANDLE_EXCEPTION)

Try the given statement, and if it fails, chain it into the given exception.

The given CONTEXT_EXCEPTION must be an expression that yields an rvalue to a std::exception subclass that isn't final . The resulting chained exception will be passed into HANDLE_EXCEPTION for processing.

◆ CELER_UNLIKELY

#define CELER_UNLIKELY ( COND ) (COND)

Mark the result of this condition to be "unlikely".

This asks the compiler to move the section of code to a "cold" part of the instructions, improving instruction locality. It should be used primarily for error checking conditions.

◆ CELER_UNREACHABLE

#define CELER_UNREACHABLE

Mark a point in code as being impossible to reach in normal execution.

See https://clang.llvm.org/docs/LanguageExtensions.html#builtin-unreachable or https://msdn.microsoft.com/en-us/library/1b3fsfxw.aspx or https://docs.nvidia.com/cuda/cuda-c-programming-guide/index.html#__builtin_unreachable

(The "unreachable" and "assume" compiler optimizations for CUDA are only available in API version 11.3 or higher, which is encoded as

major*1000 + minor*10

).

Note: This macro should not generally be used; instead, the macro CELER_ASSERT_UNREACHABLE() defined in base/Assert.hh should be used instead (to provide a more detailed error message in case the point is reached).