etl/docs/utilities/error-handler.md

title
error_handler

{{< callout type="info">}} Header: error_handler.h
{{< /callout >}}

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.

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

---

ETL_LOG_ERRORS
ETL_CHECK_PUSH_POP
 Asserts are generated when a check fails and the error handler is called and 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.