This library provides lean and mean error mechanisms. It includes c style error functions as well as a few useful macros. For higher level mechanisms, refer to ecl_exceptions.
The usual C++ means is to use exceptions, however in embedded systems, exceptions are often unavailable or are too resource-heavy. This library provides a simpler alternative, combining error flags, macros and an error handler class to provide convenient disposal of errors across multiple platforms. It also provides simple runtime and compile time asserts and aborts.
Include the following at the top of any translation unit:
You will also need to link to -lecl_errors.
The macro, @ref LOC, is a means of picking up the current file and line number of the point at which it is processed. Use with the various error functions and functors defined in ecl::errors;
A set of flags is provided through the enumeration @ref ecl::ErrorFlag "ErrorFlag". These, when coupled with the @ref ecl::Error "errorhandler" class and @ref LOC macro provide a convenient means of quickly identifying errors produced by the ecl libraries regardless of the platform that is used.
The Error class can be extended to customise the error messages - refer to the ecl_time_lite package and the ecl::TimeError class for an example.
These functions, because they are coupled with fallback macros are the only functions in the ecl not namespaced inside the ecl namespace. Rather they are prefixed with ecl_. The ecl_run_time_assert macro/function is a tool for conditional testing. It is governed by the presence of the NDEBUG macro. If NDEBUG is absent (either in your code or c-flagged by the compiler (-DNDEBUG) then run_time_assert will equate to a macro that defers to a null function pointer. This is the fastest means of bypassing debugged code. If NODEBUG is present, then ecl_run_time_assert will act as a conditional test via an function. If the test fails, it will output some data (that you have passed to the function) before finally aborting.
The abort macro/function works similarly except that it does no conditional test and it is not negated by the presence of NDEBUG.
There is also a macro which works like the compile time equivalent of ecl_run_time_assert(). This macro is useful for checking template parameters mostly. When passed a logical condition which fails, an eye-catching COMPILE_TIME_FAILURE is reported in the compile log.
Corresponding failure is reported in a format similar to the example output shown below:
A short ramble on how the ecl handles debugging can be found in this @ref debugging "guide".
Not gtests, but a useful enough coverage style test. - src/examples/errors.cpp
- @ref changelog "ChangeLog"