EBGeometry_Macros.hpp File Reference

Utility macros for EBGeometry. More...

#include <cstdio>
#include <cstdlib>
#include "EBGeometry_GPU.hpp"

Include dependency graph for EBGeometry_Macros.hpp:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros
#define	EBGEOMETRY_REQUIRE(cond, ...)
	Always-on check of user input and one-time host setup.
#define	EBGEOMETRY_EXPECT(cond)   ((void)0)
	Runtime precondition assertion for EBGeometry.

Detailed Description

Utility macros for EBGeometry.

Author

Robert Marskar

Macro Definition Documentation

EBGEOMETRY_EXPECT

#define EBGEOMETRY_EXPECT

(

cond

)

((void)0)

Runtime precondition assertion for EBGeometry.

When EBGEOMETRY_ENABLE_ASSERTIONS is defined (e.g. via -DEBGEOMETRY_ENABLE_ASSERTIONS on the compiler command line, in CXXFLAGS for GNU Make, or via CMake's target_compile_definitions), this macro evaluates cond and, if it is false, prints a diagnostic message to stderr and calls std::abort().

When EBGEOMETRY_ENABLE_ASSERTIONS is not defined the macro expands to ((void)0): cond is not evaluated at all, so an assertion costs exactly nothing in release. A variable computed solely to be asserted is then unused and must be marked [[maybe_unused]] at its declaration. On a device (CUDA/HIP) compilation pass with assertions enabled the macro prints the failing expression with the device printf and traps, instead of std::fprintf / std::abort. Unlike assert(), this does not depend on NDEBUG, which Release configurations define.

Enabling assertions

# CMake
target_compile_definitions(MyTarget PRIVATE EBGEOMETRY_ENABLE_ASSERTIONS)

# GNU Make
CXXFLAGS += -DEBGEOMETRY_ENABLE_ASSERTIONS

# Command line
g++ -DEBGEOMETRY_ENABLE_ASSERTIONS ...

Parameters

cond	Boolean-convertible expression to test.

EBGEOMETRY_REQUIRE

#define EBGEOMETRY_REQUIRE	(		cond,
			...
	)

Value:

  do {                                                                                              \
    if (!(cond)) {                                                                                  \
      std::fprintf(stderr, "EBGeometry::" __VA_ARGS__);                                             \
      std::fprintf(stderr, "\n  check: (%s)\n  file: %s\n  line: %d\n", #cond, __FILE__, __LINE__); \
      std::abort();                                                                                 \
    }                                                                                               \
  } while (0)

Always-on check of user input and one-time host setup.

Evaluates cond in every build, whether or not EBGEOMETRY_ENABLE_ASSERTIONS is defined. If it is false, prints "EBGeometry::" followed by the formatted message, the failed condition, the file and the line to stderr, and calls std::abort().

The library uses two kinds of check:

• EBGEOMETRY_EXPECT for internal invariants, including on hot paths such as a signed-distance query. It compiles to nothing unless assertions are enabled.
• EBGEOMETRY_REQUIRE for what a caller controls – constructor arguments, sizes and counts, memory resources – checked once, outside any query loop, where a Release build would otherwise continue into a wrong answer or undefined behavior. Its cost is a few comparisons per object built.

The file readers do not abort on a bad file: they throw EBGeometry::Parser::ParseError.

The message is a printf format string literal, starting with the class or function that checks, followed by its arguments:

EBGEOMETRY_REQUIRE(a_radius > T(0), "SphereSDF: the radius must be positive (%g)", double(a_radius));

On a device compilation pass (CUDA/HIP) the macro prints only the failed condition, with the device printf, and traps.

Parameters

cond	Boolean-convertible expression to test. Always evaluated.
...	A printf format string literal, then its arguments.