libexcept

The libexcept library offers us a way to automatically get a stack trace every time an exception occurs.

Introduction

The Snap! C++ environment uses a lot of exceptions, but nearly only when the exception can't be avoided (i.e. more or less a fatal error in the current situation.) Therefore, having a way to immediately discover where the exception occurred by using the libexcept exception classes gives you a way to immediately find out which function raised the exception nearly 99% of the time including in the runtime environment of Snap! C++ and any other project using the libexcept library.

Classes to Derive From

This library gives you two exception classes to derive from:

libexcept::logic_exception_t

Used to raise an exception about logic; although this is often an "emergency" type of error (even worse than a fatal error), we have a definitions for it because we raise many logic errors.

Example of a logic error:

A function is expected to receive two parameters, say both are enumerations. When the first enumeration is set to FOO then the second is expected to be one of BAR or BAZ. If the second is set to NOT_SO_GOOD instead, then the function raises a logic error because the programmer made a mistake and the problem can be fixed by fixing the code (i.e. once the code is fixed, you should then never see the error again.)

libexcept::out_of_range_t

This is an extension of the std::logic_error which is expected to be used whenever an out of range error occurs. This is mainly for when an index is out of range when attempting to retrieve an item from an array or similar concept.

libexcept::exception_t

Used for most of our exceptions. This is based on the std::runtime_error base class.

Collect a Stack Trace Creating an Object

You may also use the libexcept::exception_base_t class directly in your class(es) in order to collect a stack trace at the time the class is instantiated. The libexcept::exception_base_t::get_stack_trace() gives you the results.

libexcept::exception_base_t stack_info;
libexcept::stack_trace_t stack_dump(stack_info.get_stack_trace());
...here `stack_dump` is a list of strings, one string per frame...

By default we use STACK_TRACE_DEPTH as the number of stings to return in the libexcept::stack_trace_t vector.

Collect a Stack Trace Anywhere

Finally, you can directly call the libexcept::collect_stack_trace() function since it is a global function. It gives you a vector of strings representing the stack trace.

We also offer the libexcept::collect_stack_trace_with_line_numbers() for debug only. The exceptions do not make use of that function by default because it is way too slow. It is useful to convert the frame IP addresses to line numbers (assuming you still have debug information in your text files and the software can find the text file concerned by the problem.)

Thread Safety

The library is thread safe. All the functions are reentrant except the set_collect_stack(), which is still safe to use, only the results may not always be exactly as expected.

In terms of parallelism, the collect_stack_trace_with_line_numbers() runs some console processes to collect the line number and demangle the function names. This means that it could be really heavy if many threads use that function often.