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>

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...

Typedefs
using	Config = LumieraError< LERR_(CONFIG), Invalid >

using	CStr = const char *

using	External = LumieraError< LERR_(EXTERNAL)>

using	Fatal = LumieraError< LERR_(FATAL), Logic >

using	Flag = LumieraError< LERR_(FLAG), State >

using	Invalid = LumieraError< LERR_(INVALID)>

using	Logic = LumieraError< LERR_(LOGIC)>

using	State = LumieraError< LERR_(STATE)>

Macros
#define	_STDBOOL_H

#define	ERROR_LOG_AND_IGNORE(_FLAG_, _OP_DESCR_)
	convenience shortcut for a sequence of catch blocks just logging and consuming an error. More...

#define	ERROR_LOG_AND_RETHROW(_FLAG_, _OP_DESCR_)

#define	LERR_(_NAME_) lumiera::error::LUMIERA_ERROR_##_NAME_

#define	ON_EXCEPTION_RETURN(_VAL_, _OP_DESCR_)
	convenience shortcut to catch and absorb any exception, then returning a default value instead. More...

Functions
void	assertion_terminate (const string &location)
	throw an error::Fatal indicating "assertion failure"

CStr	detailInfo ()

void	install_unexpectedException_handler ()
	install our own handler for undeclared exceptions. More...

	LUMIERA_ERROR_DECLARE (EXCEPTION)
	error-ID for unspecified exceptions

	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	lumiera_unexpectedException () noexcept
	global function for handling unknown exceptions encountered at functions declaring not to throw this kind of exception. More...

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. More...

void	throwOnError ()
	Check the lumiera error state, which maybe was set by C-code. More...

Namespaces
	lumiera
	Lumiera public interface.

Macro Definition Documentation

◆ ERROR_LOG_AND_IGNORE

#define ERROR_LOG_AND_IGNORE	(	_FLAG_,
		_OP_DESCR_
	)

Value:

catch (std::exception& problem)                \
    {                                             \
      const char* errID = lumiera_error();         \
      WARN (_FLAG_, "%s failed: %s", _OP_DESCR_, problem.what()); \
      TRACE (debugging, "Error flag was: %s", errID);\
    }                                                 \
  catch (...)                                          \
    {                                                   \
      const char* 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 275 of file error.hpp.

Referenced by GuiSubsysDescriptor::checkRunningState(), LinkedElements< Prerequisite >::clear(), DispatcherLoop::DispatcherLoop(), BufferProvider::emergencyCleanup(), ThreadWrapper::invokedWithinThread(), Worker< vault::gear::Scheduler::Setup >::isDead(), ScopedCollection< CON >::pull(), BufferProvider::releaseBuffer(), SteamDispatcher::requestStop(), GuiSubsysDescriptor::triggerShutdown(), and AllocatorHandle< JobTicket >::~AllocatorHandle().

◆ ERROR_LOG_AND_RETHROW

#define ERROR_LOG_AND_RETHROW	(	_FLAG_,
		_OP_DESCR_
	)

Value:

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

Definition at line 290 of file error.hpp.

◆ ON_EXCEPTION_RETURN

#define ON_EXCEPTION_RETURN	(	_VAL_,
		_OP_DESCR_
	)

Value:

catch (std::exception& problem)                \
    {                                             \
      const char* errID = lumiera_error();         \
      WARN (stage, "%s (Handler) failed: %s",       \
                   _OP_DESCR_, problem.what());      \
      TRACE (debugging, "Error flag was: %s", errID); \
      return (_VAL_);                                  \
    }                                                   \
  catch (...)                                            \
    {                                                     \
      const char* 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 313 of file error.hpp.

Function Documentation

◆ lumiera_unexpectedException()

void lumiera_unexpectedException ( )

noexcept

global function for handling unknown exceptions encountered at functions declaring not to throw this kind of exception.

Basically, any such event can be considered a severe design flaw; we can just add some diagnostics prior to halting.

Definition at line 176 of file error-exception.cpp.

References cStr(), Error::getID(), Error::getUsermsg(), lumiera::error::lumiera_unexpectedException(), and Error::what().

Referenced by lumiera::error::install_unexpectedException_handler(), and lumiera::error::lumiera_unexpectedException().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ install_unexpectedException_handler()

void lumiera::error::install_unexpectedException_handler ( )

install our own handler for undeclared exceptions.

Will be called automatically ON_BASIC_INIT when linking exception.cpp

Definition at line 166 of file error-exception.cpp.

References lumiera::error::lumiera_unexpectedException().

Here is the call graph for this function:

◆ detailInfo()

CStr detailInfo ( )

Returns: error detail-info if currently set, a default message else

Definition at line 64 of file error-exception.cpp.

References lumiera::error::detailInfo(), and lumiera_error_extra().

Referenced by lumiera::error::detailInfo().

Here is the call graph for this function:

Here is the caller graph for this function:

Description

Classes

Typedefs

Macros

Functions

Namespaces

Macro Definition Documentation

◆ ERROR_LOG_AND_IGNORE

◆ ERROR_LOG_AND_RETHROW

◆ ON_EXCEPTION_RETURN

Function Documentation

◆ lumiera_unexpectedException()

◆ install_unexpectedException_handler()

◆ detailInfo()