mirror of
https://github.com/ETLCPP/etl.git
synced 2026-06-15 16:36:03 +08:00
167 lines
8.9 KiB
Plaintext
167 lines
8.9 KiB
Plaintext
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_USE_ASSERT_FUNCTION Errors are sent to a user defined assert handler.
|
|
• 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.
|
|
____________________________________________________________________________________________________
|
|
There are versions of the assert macros that are only enabled when ETL_IS_DEBUG_BUILD is true:-
|
|
|
|
ETL_DEBUG_ASSERT(condition, ETL_ERROR(error_exception_class))
|
|
Raises the error if the condition is false.
|
|
____________________________________________________________________________________________________
|
|
ETL_DEBUG_ASSERT_AND_RETURN(condition, ETL_ERROR(error_exception_class))
|
|
Raises the error if the condition is false and calls return.
|
|
____________________________________________________________________________________________________
|
|
ETL_DEBUG_ASSERT_AND_RETURN_VALUE(condition, ETL_ERROR(error_exception_class), value)
|
|
Raises the error if the condition is false and calls return(value).
|
|
____________________________________________________________________________________________________
|
|
ETL_DEBUG_ALWAYS_ASSERT(ETL_ERROR(error_exception_class))
|
|
Raises the error.
|
|
____________________________________________________________________________________________________
|
|
ETL_DEBUG_ALWAYS_ASSERT_AND_RETURN(ETL_ERROR(error_exception_class))
|
|
Raises the error and calls return.
|
|
____________________________________________________________________________________________________
|
|
ETL_DEBUG_ALWAYS_ASSERT_AND_RETURN_VALUE(ETL_ERROR(error_exception_class), value)
|
|
Raises the error and calls return(value).
|
|
____________________________________________________________________________________________________
|
|
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_USE_ASSERT_FUNCTION Calls a user defined assert function. Set with etl::set_assert_function()
|
|
The assert function must have the signature void(const etl::exception&)
|
|
If an assert handler is not specified then assert(false) is called.
|
|
____________________________________________________________________________________________________
|
|
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
|
|
int main()
|
|
{
|
|
etl::error_handler::set_callback<free_function>();
|
|
}
|
|
____________________________________________________________________________________________________
|
|
Setting a member function as the recipient
|
|
|
|
error_log log;
|
|
|
|
// Run-time
|
|
int main()
|
|
{
|
|
etl::error_handler::set_callback<error_log, &error_log::member_function>(log);
|
|
}
|
|
|
|
// Compile-time. 'log' must have static linkage.
|
|
int main()
|
|
{
|
|
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
|
|
int main()
|
|
{
|
|
// 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.
|
|
|