fe_trap Class Reference

Floating-point exception trap. More...

#include <fe_trap.hpp>

Public Member Functions
	fe_trap (fe_trap const &)=delete
	fe_trap (fe_trap &&) noexcept=delete
fe_trap &	operator= (fe_trap const &)=delete
fe_trap &	operator= (fe_trap &&) noexcept=delete
int	get_flags () const
	Get floating-point exception flags.
bool	is_unique () const
	Check if this handle is a unique handle.
bool	is_active () const
	Check if this handle has a currrently active trap.
void	activate ()
	Manually activate the exception trap.
void	deactivate ()
	Manually deactivate the exception trap.

Static Public Member Functions
static scoped_instance	make_unique_scoped (std::optional< int > excepts=std::nullopt)
	Generate a unique trap with the lifetime of the current scope.
static scoped_instance	make_shared_scoped (std::optional< int > excepts=std::nullopt)
	Generate a shared trap with the lifetime of the current scope.
static std::shared_ptr< scoped_pause >	make_shared_pause_scoped ()
	Generate a shared handle to temporarily disable any currently active exception trap for the lifetime of the current scope.

Detailed Description

Floating-point exception trap.

Thread-safe RAII-style mechanism to trap floating-point exceptions (on platforms that support floating-point environment management) for the duration of a scoped block. Exception traps are set when the object is created; when getting out-of-scope, either normally or during stack unwinding, the exception traps are automatically reset. This idiom is called "scope-based resource management".

Please note "exception" and "exception handling" have a specific meaning in this context and are completely unrelated to C++ exceptions. For more details, see annex F IEC 60559 "floating-point arithmetic" in ISO/EIC 9899 [24] and chapter 7 "Exceptions and default exception handling" in ISO/IEC 60559:2020(E) [25].

The exception handling behavior is implementation-defined. For example, GNU libc sends the SIGFPE signal on x86 architectures; it can be caught by a signal handler that leverages stack environments and long jumps via sigsetjmp(). On Armv8, trapping is controlled by FPCR flags; for more details, see section C5.2.8 "FPCR, Floating-point Control Register" in the Armv8 manual [5]. AppleClang sends the SIGILL signal on Apple Silicon architectures.

A modified singleton pattern is leveraged to guarantee only one trap is active at any time; once expired, a new trap can be instantiated. The make_unique_scoped function returns a wrapper object whose lifetime determines the trap duration. To set a trap in a recursive function, use make_shared_scoped instead.

Usage:

#include <instrumentation/fe_trap.hpp>
#include <cmath>
int main() {
  auto volatile zero = 0.;
  auto value = 1. / zero;  // generate NaN
  {
    auto trap = fe_trap::make_unique_scoped();
    value = 1. / zero;  // execution flow should be interrupted here
  }
  value = 1. / zero;  // generate NaN
  return std::isnan(value) ? 0 : 1;
}

Build the code without fast-math and without any optimization (optimizations always assume divisions by zero cannot happen):

g++ -std=c++20 -O0 -fno-fast-math -I../src/instrumentation/include \
    -I../src/config/include -Isrc/config/include \
    main.cpp ../src/instrumentation/src/fe_trap.cpp
./a.out
}

Definition at line 88 of file fe_trap.hpp.

Constructor & Destructor Documentation

fe_trap() [1/2]

fe_trap::fe_trap ( fe_trap const &  )

delete

fe_trap() [2/2]

fe_trap::fe_trap ( fe_trap &&  )

deletenoexcept

Member Function Documentation

activate()

void fe_trap::activate

(

)

Manually activate the exception trap.

Definition at line 42 of file fe_trap.cpp.

deactivate()

void fe_trap::deactivate

(

)

Manually deactivate the exception trap.

Useful when calling a third-party library that is known to send signals. This should only be used in exceptional cases (make_shared_pause_scoped provides a scope-based alternative). Call activate() to re-activate the exception trap.

Definition at line 72 of file fe_trap.cpp.

get_flags()

int fe_trap::get_flags ( ) const

inline

Get floating-point exception flags.

Definition at line 152 of file fe_trap.hpp.

is_active()

bool fe_trap::is_active ( ) const

inline

Check if this handle has a currrently active trap.

Definition at line 156 of file fe_trap.hpp.

is_unique()

bool fe_trap::is_unique ( ) const

inline

Check if this handle is a unique handle.

Definition at line 154 of file fe_trap.hpp.

make_shared_pause_scoped()

std::shared_ptr< fe_trap::scoped_pause > fe_trap::make_shared_pause_scoped ( )

static

Generate a shared handle to temporarily disable any currently active exception trap for the lifetime of the current scope.

If no exception trap is currently active, return a null pointer.

Definition at line 144 of file fe_trap.cpp.

Referenced by ScriptInterface::walberla::EKFFT::make_instance(), and p3m_gpu_init().

make_shared_scoped()

fe_trap::scoped_instance fe_trap::make_shared_scoped ( std::optional< int >  excepts = std::nullopt )

static

Generate a shared trap with the lifetime of the current scope.

Subsequent calls to this function will yield the same trap handle, as long as they have the same parameter excepts.

Parameters

excepts

Combination of floating-point exception flags.

Definition at line 126 of file fe_trap.cpp.

Referenced by ScriptInterface::ObjectHandle::call_method(), and ScriptInterface::ObjectHandle::set_parameter().

make_unique_scoped()

fe_trap::scoped_instance fe_trap::make_unique_scoped ( std::optional< int >  excepts = std::nullopt )

static

Generate a unique trap with the lifetime of the current scope.

Parameters

excepts

Combination of floating-point exception flags.

Definition at line 114 of file fe_trap.cpp.

operator=() [1/2]

fe_trap & fe_trap::operator= ( fe_trap &&  )

deletenoexcept

operator=() [2/2]

fe_trap & fe_trap::operator= ( fe_trap const &  )

delete

---

The documentation for this class was generated from the following files:

• fe_trap.hpp
• fe_trap.cpp