Introduction

The Snap! C++ project makes use of exceptions whenever it bumps in a problem which can't be resolved at the time it is detected.

This model means that exceptions are usually fairly rare (once in a while we have a problem and generate problematic exceptions, but we tend to fix those quickly.) In other words, our exceptions are pretty exceptional. For example, a file can't be opened when it should, we are likely to throw a Run Time Exception.

As a result, it is possible for us to do something rather slow in our exceptions:

Collect a Stack Trace

This helps us greatly especially because we have many calls and sub-calls to many different functions all of which may throw an exception. We had several cases where we though A was calling B, when in reality that exception occurred because C was calling B. That changed the perspective and we could immediately fix the bug once we knew who called what.

Now we have that integrated in our system. Actually, it will print the stack trace in our logs. This means we get logs with stack trace of programs running on customers' systems. This makes it very easy to fix many bugs and allows our code to be much more stable much faster.

Download

The source code is available on github.com.

Packages

You can directly download the packages by installing our Snap! C++ PPA on your Ubuntu system and then running the apt-get install command. The name of the package is libexcept.

Building

In the Snap! C++ environment, we make use of CMake. You will need the snapcmakemodules to compile libexcept.

However, the library is really small and creating a new project which matches your project or even just adding the two files (exception.cpp and exception.h) in your project may be much easier.

Compatibility

At this time, this library only works on Linux.

Coverage Test Results

Access full page here.

The library has a test suite that covers 100% of the code, making it a little more certain that it does not include too many bugs. We try to run the tests each time we create a new version to ensure that it works as expected.

Change Logs

• 1.1.0

Added a function to collect a stack trace with demangled function names and line numbers when available.

Made the collect stack trace functions available publicly.

Added a function to turn off stack trace on exception. Particularly useful when running tests which verify that exceptions do occur as expected.

• 1.0.5

Added a documentation package.

Fixed many small mistakes in the package definitions.

Made the stack trace depth accessible to classes that derive the libexcept exceptions.

• 1.0.4

The code is Effective C++ compatible.

• 1.0.3

Added a version.cpp file.

• 1.0.2

Removed all dependencies on Qt.

• 1.0.0

Created the libexcept from the snap exception implementation.

At that time we kept a seperate snap exception class in the snapwebsites library. We are planning to convert our snapwebsites library at some point. The functionality was not 1 to 1 equivalent which is why we kept both (i.e. the snapwebsites library supports Qt for example.)