error.hpp File Reference

Lumiera error handling (C++ interface). More...

Go to the source code of this file.

Description

Lumiera error handling (C++ interface).

This header declares the Lumiera exception hierarchy, plus some of the most commonly used error flag values. Within Lumiera, C-style error states and C++-style exceptions are tightly integrated. Creating an exception sets the error flag, and there are helpers available to throw an exception automatically when a unclear error state is detected.

See also

error-state.c

error.hpp

Definition in file error.hpp.

#include "include/logging.h"
#include "lib/hash-standard.hpp"
#include "lib/error.h"
#include <exception>
#include <string>

Namespaces
namespace	lumiera
	Lumiera public interface.
namespace	lumiera::error

Macros
#define	_STDBOOL_H
#define	LERR_(_NAME_)   lumiera::error::LUMIERA_ERROR_##_NAME_
#define	ERROR_LOG_AND_IGNORE(_FLAG_, _OP_DESCR_)
	convenience shortcut for a sequence of catch blocks just logging and consuming an error.
#define	ERROR_LOG_AND_RETHROW(_FLAG_, _OP_DESCR_)
#define	ON_EXCEPTION_RETURN(_VAL_, _OP_DESCR_)
	convenience shortcut to catch and absorb any exception, then returning a default value instead.

Typedefs
using	CStr = const char *
using	Logic = LumieraError< LERR_(LOGIC)>
using	Fatal = LumieraError< LERR_(FATAL), Logic >
using	State = LumieraError< LERR_(STATE)>
using	Flag = LumieraError< LERR_(FLAG), State >
using	Invalid = LumieraError< LERR_(INVALID)>
using	Config = LumieraError< LERR_(CONFIG), Invalid >
using	External = LumieraError< LERR_(EXTERNAL)>

Classes
class	Error
	Interface and Base definition for all Lumiera Exceptions. More...
class	LumieraError< eID, PAR >
	Derived specific exceptions within Lumiera's exception hierarchy. More...

Functions
	LUMIERA_ERROR_DECLARE (EXCEPTION)
	error-ID for unspecified exceptions
void	lumiera_unexpectedException () noexcept
	global function for handling unknown exceptions encountered at functions declaring not to throw this kind of exception.
void	assertion_terminate (const string &location)
	throw an error::Fatal indicating "assertion failure"
	LUMIERA_ERROR_DECLARE (LOGIC)
	contradiction to internal logic assumptions detected
	LUMIERA_ERROR_DECLARE (FATAL)
	unable to cope with, internal logic floundered
	LUMIERA_ERROR_DECLARE (CONFIG)
	execution aborted due to misconfiguration
	LUMIERA_ERROR_DECLARE (STATE)
	unforeseen internal state
	LUMIERA_ERROR_DECLARE (FLAG)
	non-cleared lumiera errorstate from C code
	LUMIERA_ERROR_DECLARE (INVALID)
	invalid input or parameters encountered
	LUMIERA_ERROR_DECLARE (EXTERNAL)
	failure in external service the application relies on
	LUMIERA_ERROR_DECLARE (ASSERTION)
	assertion failure
	LUMIERA_ERROR_DECLARE (LIFECYCLE)
	Lifecycle assumptions violated.
	LUMIERA_ERROR_DECLARE (WRONG_TYPE)
	runtime type mismatch
	LUMIERA_ERROR_DECLARE (ITER_EXHAUST)
	end of sequence reached
	LUMIERA_ERROR_DECLARE (CAPACITY)
	predefined fixed storage capacity
	LUMIERA_ERROR_DECLARE (SAFETY_LIMIT)
	exceeding fixed internal safety limit
	LUMIERA_ERROR_DECLARE (INDEX_BOUNDS)
	index out of bounds
	LUMIERA_ERROR_DECLARE (BOTTOM_VALUE)
	invalid or NIL value
	LUMIERA_ERROR_DECLARE (UNCONNECTED)
	missing connection
	LUMIERA_ERROR_DECLARE (UNIMPLEMENTED)
	unimplemented feature
void	install_unexpectedException_handler ()
	install our own handler for undeclared exceptions.
CStr	detailInfo ()
void	throwOnError ()
	Check the lumiera error state, which maybe was set by C-code.
template<class EX >
void	maybeThrow (string description="")
	Check the lumiera error state and throw a specific exception in case a non-cleared errorflag is detected.

Typedef Documentation

CStr

using CStr = const char*

Definition at line 42 of file error.hpp.

Macro Definition Documentation

_STDBOOL_H

#define _STDBOOL_H

Definition at line 33 of file error.hpp.

LERR_

#define LERR_

(

_NAME_

)

lumiera::error::LUMIERA_ERROR_##_NAME_

Definition at line 45 of file error.hpp.

ERROR_LOG_AND_IGNORE

#define ERROR_LOG_AND_IGNORE	(		_FLAG_,
			_OP_DESCR_
	)

Value:

  catch (std::exception& problem)                \
    {                                             \
      CStr errID = lumiera_error();                \
      WARN (_FLAG_, "%s failed: %s", _OP_DESCR_, problem.what()); \
      TRACE (debugging, "Error flag was: %s", errID);\
    }                                                 \
  catch (...)                                          \
    {                                                   \
      CStr errID = lumiera_error();               \
      ERROR (_FLAG_, "%s failed with unknown exception; " \
                     "error flag is: %s"                   \
                   , _OP_DESCR_, errID?errID:"??");         \
    }

convenience shortcut for a sequence of catch blocks just logging and consuming an error.

Typically this sequence will be used within destructors, which, by convention, must not throw

Definition at line 267 of file error.hpp.

ERROR_LOG_AND_RETHROW

#define ERROR_LOG_AND_RETHROW	(		_FLAG_,
			_OP_DESCR_
	)

Value:

  catch (std::exception& problem)                 \
    {                                              \
      CStr errID = lumiera_error();                 \
      WARN (_FLAG_, "%s failed: %s", _OP_DESCR_, problem.what()); \
      TRACE (debugging, "Error flag was: %s", errID); \
      throw;                                           \
    }                                                   \
  catch (...)                                            \
    {                                                     \
      CStr errID = lumiera_error();                        \
      ERROR (_FLAG_, "%s failed with unknown exception; "   \
                     "error flag is: %s"                     \
                   , _OP_DESCR_, errID?errID:"??");           \
      throw;                                                   \
    }

Definition at line 282 of file error.hpp.

ON_EXCEPTION_RETURN

#define ON_EXCEPTION_RETURN	(		_VAL_,
			_OP_DESCR_
	)

Value:

  catch (std::exception& problem)                \
    {                                             \
      CStr errID = lumiera_error();                \
      WARN (stage, "%s (Handler) failed: %s",       \
                   _OP_DESCR_, problem.what());      \
      TRACE (debugging, "Error flag was: %s", errID); \
      return (_VAL_);                                  \
    }                                                   \
  catch (...)                                            \
    {                                                     \
      CStr errID = lumiera_error();                        \
      ERROR (stage, "(Handler) %s failed with "             \
                    "unknown exception; error flag is: %s"   \
                   , _OP_DESCR_, errID?errID:"??");           \
      return (_VAL_);                                          \
    }

convenience shortcut to catch and absorb any exception, then returning a default value instead.

This scheme is typically used within signal handlers in the GTK UI, since GTK (written in C) can not propagate exceptions

Definition at line 305 of file error.hpp.