A C++ template library for embedded applications
Designed and maintained by
Aster Consulting Ltd

error_handler

Finding errors within an embedded system can be difficult due to the performance and space restrictions imposed upon
the platform. The library allows a variety of methods to catch errors, allowing the performance and space overheads to be
chosen according to the situation and requirements.

The library allows the method to be chosen at compile time.

• Exceptions
• Asserts
• Error log
• No error checking

The type of error handler used is dependant on the compile time macro defined.
Note: This are usually set as a project wide definition.

ETL_NO_CHECKS        No checks are mode at all, not even in debug mode.
ETL_THROW_EXCEPTIONS Exceptions are thrown for an error.
ETL_LOG_ERRORS       Errors are sent to a user defined error handler.
                      This can be used in conjunction with other options.

If none of the above macros are defined then the library will use asserts. These are only active is NDEBUG is not defined.

Errors are checked for by calling ETL_ASSERT(condition, ETL_ERROR(error_exception_class))

If ETL_VERBOSE_ERRORS is defined then the filename is included as part of the error, otherwise it will be omitted, so
reducing storage requirements.

Error messages by be declared using the ETL_ERROR_TEXT macro.
ETL_ERROR_TEXT("Verbose text", "terse text")
If ETL_VERBOSE_ERRORS is defined then ETL_TEXT uses the verbose text. By default the terse text is used.

The terse text used in the library follows a <numeric><alpha> pattern. For example, errors in etl::vector start with "17"
and the alpha code for 'vector full' is "A". The return from the what() member function in this case will be "17A".

When ETL_LOG_ERRORS is defined error exceptions are passed to etl::error_handler::error() before throwing the
exception or calling the assert. This will do nothing until a user defined handler function is set. The user function may
either be a free function or a member function.

There is an additional switch that enables checks to be made on pushes and pops to containers, ETL_CHECK_PUSH_POP.
This is not enabled by default as empty/full checks will usually be made by the calling code.

Example macro combinations



















Example error handlers

void free_error_handler(const etl::exception& e)
{
  std::cout << "The error was " << e.what() << " in " << e.file_name() << " at "
            << e.line_number() << "\n";
}

struct handler_error
{
  void member_error_handler(const etl::exception& e)
  {
    std::cout << "The error was " << e.what() << " in " << e.file_name() << " at "
              << e.line_number() << "\n";
  }
};

Setting a free function as the recipient

error_handler::free_function callback(free_error_handler);

error_handler::set_callback(callback);

Setting a member function as the recipient

error_log handler;

error_handler::member_function<handler_error> callback(handler,
                                                       &error_log::member_error_handler));

error_handler::set_callback(callback);  
No error macros defined Asserts are generated when a check fails.
ETL_LOG_ERRORS Asserts are generated when a check fails and the error handler is called.
ETL_NO_CHECKS No checks are made. No asserts or exceptions are generated.
No calls to the error handler are made, even if
ETL_LOG_ERRORS is defined.
ETL_THROW_EXCEPTIONS An exception is thrown when a check fails.
ETL_THROW_EXCEPTIONS
ETL_LOG_ERRORS
An exception is thrown when a check fails and the error handler is called.
ETL_LOG_ERRORS
ETL_CHECK_PUSH_POP
Asserts are generated when a check fails and the error handler is called.
Additional checks for pushes and pops are made.
error_handler.h