ecl_errors Documentation

ecl_errors

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.

• Homepage: http://wiki.ros.org/ecl_errors

Embedded Control Library

    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.

Compiling & Linking

    Include the following at the top of any translation unit:

#include <ecl/errors.hpp>

// The error interfaces
using ecl_compile_time_assert;
using ecl_run_time_assert;
using ecl_run_time_abort;

// Error type enumerations
using ecl::NoError;
using ecl::ConfigurationError;
using ecl::UnknownError;
//...

// Error Handler
using ecl::Error;

You will also need to link to -lecl_errors.

Usage

LOC

            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;

Error Handling

            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.

ecl::Error void f(const int &i) const {
    if ( i == 3 ) {
        return ecl::Error(ecl::NoError);
    } else {
        return ecl::Error(ecl::OutOfRangeError);
    }
int main() {
    ecl::Error error = f(5);
    if ( error.flag() != NoError() ) {
        error.print(loc);  
    }
    // output is ~ 'my_main.cpp : 31 - Out of range error.'
    return 0;
}

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.

Assert and Abort Functions

            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.

int i = 3;
int j = 2;
ecl_run_time_assert(i < j, LOC, "Illegal context, need i < j");

The abort macro/function works similarly except that it does no conditional test and it is not negated by the presence of NDEBUG.

Compile Time Equivalents

            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.

ecl_compile_time_assert( 1 > 3 )

Corresponding failure is reported in a format similar to the example output shown below:

test.cpp:47: error: invalid application of ‘sizeof’ to incomplete type ‘COMPILE_TIME_FAILURE<false>’ 

Other Notes

    A short ramble on how the ecl handles debugging can be found in this @ref debugging "guide".

Unit Tests

    Not gtests, but a useful enough coverage style test.

    - src/examples/errors.cpp

ChangeLog

    - @ref changelog "ChangeLog"