Error-handling

Error handling tools. More...

Functions
SIPLASPLAS_UTILITY_EXPORT spdlog::logger &	cpp::utility::errorLogger ()
	Isolated logger for detailed error logging. More...
template<typename Message , typename... Args>
void	cpp::utility::logErrorSkippingFrames (std::size_t framesToSkip, const Message &message, Args &&...args)
	Log an error with its backtrace. Also skip the latest framesToSkip stack frames from stack trace. More...
template<typename Message , typename... Args>
void	cpp::utility::logError (const Message &message, Args &&...args)
	Logs an error with its backtrace. See cpp::logErrorSkippingFrames(). More...
template<typename Ex , typename Message >
void	cpp::logException (const Message &message, std::size_t framesToSkip=0)
	Logs an error message from an exception. More...
template<typename Ex >
void	cpp::logException (const Ex &exception, std::size_t framesToSkip=0)
	Logs an exception. More...
template<typename Exception , typename... Args>
Exception	cpp::exceptionSkippingFrames (std::size_t framesToSkip, const std::string &message, Args &&...args)
	Instances an exception with a custom error message. More...
template<typename Exception , typename... Args>
Exception	cpp::exception (const std::string &message, Args &&...args)
	Instances an exception with a custom error message. More...

Detailed Description

Error handling tools.

This submodule contains tools to handle errors in different ways and get detailed error reports.

Todo:

cpp::Expect template for "fast" error handling.

Function Documentation

SIPLASPLAS_UTILITY_EXPORT spdlog::logger& cpp::utility::errorLogger

(

)

Isolated logger for detailed error logging.

This function returns a logger pointing to an isolated siplasplas errors log file. All exceptions and assertion failures are logged throught this logger.

Returns

Reference to the spdlog logger.

template<typename Exception , typename... Args>

Exception cpp::exception	(	const std::string &	message,
		Args &&...	args
	)

Instances an exception with a custom error message.

This function creates an exception object of the given type using a custom parameterized error message (See fmt::format()). Exceptions instanced throught this function are reported automatically (See cpp::logError() and cpp::logException()).

Template Parameters

Exception

Exception type to instance.

Parameters

message	Exception error message. May have message argument placeholders. See fmt::format().
args	Error message arguments.

Returns

A Exception instance with the specified error message.

template<typename Function>
void businessLogic(Function callback)
{
    callback();
}

int main()
{
    businessLogic([]
    {
        // throw an error skipping the callback frame from the report backtrace:
        throw exceptionSkippingFrames<std::runtime_error>(1, "Look, a runtime error!");
    });
}

template<typename Exception , typename... Args>

Exception cpp::exceptionSkippingFrames	(	std::size_t	framesToSkip,
		const std::string &	message,
		Args &&...	args
	)

Instances an exception with a custom error message.

This function creates an exception object of the given type using a custom parameterized error message (See fmt::format()). Exceptions instanced throught this function are reported automatically (See cpp::logError() and cpp::logException()).

Template Parameters

Exception

Exception type to instance.

Parameters

framesToSkip	Number of lower frames to skip from the report backtrace. See cpp::logErrorSkippingFrames().
message	Exception error message. May have message argument placeholders. See fmt::format().
args	Error message arguments.

Returns

A Exception instance with the specified error message.

template<typename Function>
void businessLogic(Function callback)
{
    callback();
}

int main()
{
    businessLogic([]
    {
        // throw an error skipping the callback frame from the report backtrace:
        throw exceptionSkippingFrames<std::runtime_error>(1, "Look, a runtime error!");
    });
}

template<typename Message , typename... Args>

void cpp::utility::logError	(	const Message &	message,
		Args &&...	args
	)

Logs an error with its backtrace. See cpp::logErrorSkippingFrames().

Effectively calls logErrorSkippingFrames(1, message, args...).

Parameters

message	Error message. May contain argument placeholders.
args	Error message arguments.

logError("unexpected error! (errno={}", errno);

template<typename Message , typename... Args>

void cpp::utility::logErrorSkippingFrames	(	std::size_t	framesToSkip,
		const Message &	message,
		Args &&...	args
	)

Log an error with its backtrace. Also skip the latest framesToSkip stack frames from stack trace.

This function logs a detailed error report with a stack trace ending at the caller function. Also supports skipping the last framesToSkip stack frames from the trace in case the trace is invoked from an API with multiple implementation layers. The generated report follows the format:

#i "<binary file>", at <address> in <function>
#i-1 "<binary file>", at <address> in <function>
...
#1 "<binary file>", at <address> in <function>
#0 "<binary file>", at <address> in <function>

<error message>

where the lower (of index 0) line in the backtrace is the latest (caller) stack frame. The error message is logged with critical level and the backtrace with debug level. The backtrace supports a max of 32 frames. If the backtrace is longer, uppermost frames will be ignored.

Parameters

framesToSkip	Number of lower frames to skip from the backtrace.
message	Error message. May contain argument placeholders. See fmt::format().
args	Error message arguments.

void justBecauseExceptionsAreSlow(int i)
{
   // Because we miss nodejs, let's callback everything!
   auto callback = []
   {
       if(i != 42)
       {
           // Log an error skipping the callback frame:
           cpp::logErrorSkippingFrames(1, "Error: {} is not a valid answer Deep Thought!", i);
       }
   };

   callback();
}

template<typename Ex , typename Message >

void cpp::logException	(	const Message &	message,
		std::size_t	framesToSkip = 0
	)

Logs an error message from an exception.

This function logs an error report (See cpp::logError()) about a thrown exception. The error report is of the form:

'<exception type>' exception thrown: <message>

Template Parameters

Ex	Type of the exception.

Parameters

message	Exception message.
framesToSkip	Number of frames to skip from the backtrace. Default is cero. See cpp::logErrorSkippingFrames().

try
{
   throwingMan();
}
catch(const std::runtime_error& ex)
{
    logException<std::runtime_error>(ex.what());
}

template<typename Ex >

void cpp::logException	(	const Ex &	exception,
		std::size_t	framesToSkip = 0
	)

Logs an exception.

This function logs a detailed error report from an exception object. See cpp::logError(). The error report is of the form:

'<exception type>' exception thrown: <exception.what()>

Parameters

exception	Exception object. The error message for the report is get from exception.what().
framesToSkip	Number of frames to skip from the backtrace. Default is cero. See cpp::logErrorSkippingFrames().

try
{
   throwingMan();
}
catch(const std::runtime_error& ex)
{
    logException(ex);
}