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 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_LOG_ERRORS When a check fails the error handler is called, then an exception is thrown.

ETL_THROW_EXCEPTIONS

____________________________________________________________________________________________________

ETL_LOG_ERRORS Asserts are generated when a check fails and the error handler is called and

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