A C++ template library for embedded applications
MIT licensed
Designed and
maintained by
John Wellbelove
Support the development
of the ETL

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.

You have a choice of:-
• 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 assert. These are only active is NDEBUG is not defined.
____________________________________________________________________________________________________
Errors are checked for by calling one of the following:-
ETL_ASSERT(condition, ETL_ERROR(error_exception_class))
Raises the error if the condition is false.
ETL_ASSERT_AND_RETURN(condition, ETL_ERROR(error_exception_class))
Raises the error if the condition is false and calls return.
ETL_ASSERT_AND_RETURN_VALUE(condition, ETL_ERROR(error_exception_class), value)
Raises the error if the condition is false and calls return(value).

ETL_ALWAYS_ASSERT(ETL_ERROR(error_exception_class))
Raises the error.
ETL_ALWAYS_ASSERT_AND_RETURN(ETL_ERROR(error_exception_class))
Raises the error and calls return.
ETL_ALWAYS_ASSERT_AND_RETURN_VALUE(ETL_ERROR(error_exception_class), value)
Raises the error and calls return(value).

Note: Not all error methods will call the return, such as when using C++ exceptions.
The macro will call return for the following combinations:-
ETL_LOG_ERRORS only.
ETL_DEBUG not defined.
____________________________________________________________________________________________________
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

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      An exception is thrown when a check fails and the error handler is called.
ETL_LOG_ERRORS

ETL_LOG_ERRORS            Asserts are generated when a check fails and the error handler is called.
ETL_CHECK_PUSH_POP        Additional checks for pushes and pops are made.

____________________________________________________________________________________________________

Example error handlers


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

struct error_log
{
  void member_function(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


etl::error_handler::set_callback<free_function>();
____________________________________________________________________________________________________
Setting a member function as the recipient

error_log log;

// Run-time
etl::error_handler::set_callback<error_log, &error_log::member_function>(log);

// Compile-time. 'log' must have static linkage.
etl::error_handler::set_callback<error_log, log, &error_log::member_function>();
____________________________________________________________________________________________________
Setting an etl::ifunction as the recipient
This is not recommended for new applications.
Use one of the methods above instead.

// Free function
etl::function<void, const etl::exception&> error_callback(free_function);

// Member function
etl::function<TObject, const etl::exception&> error_callback(log, &error_log::member_function);

// Free function using the nested struct (Deprecated)
etl::error_handler::free_function error_callback(free_function);

// Member function using the nested struct (Deprecated)
etl::error_handler::member_function error_callback(log, error_log::member_function);

Use one of the above
// Tell the error handler about it.
etl::error_handler::set_callback(error_callback);
____________________________________________________________________________________________________
Deprecated
The nested structures free_function and member_function may still be used, but are deprecated.
error_handler.h