Title: Techniques for Debugging in C++

When talking about debugging techniques here I'm going to deliberately avoid mention of a debugger. Why? Well, a debugger is not always present on every platform (I've recently been playing with some embedded environments where a debugger was not easily available). Nothing can compare to the power of using a debugger to "get into" program execution, but when a debugger is not available we still need an arsenal of techniques to allow us to debug effectively.

Besides, oranges are not the only fruit - a debugger is not the only tool to aid debugging. It's good for dissecting a program that doesn't work properly, but it's not too handy to pre-emptively detect code that could cause problems later down the line.

In this article I focus more on constraint-based techniques for ensuring our code is bug free. That is, writing some extra code (that can be compiled out at build-time, if necessary) that enforces a set of logical constraints. These constraints define whether or not the program is operating correctly.

If constraints are added in at the smallest granularity in the code-base then the maximum benefit is achieved - most of the code is sanity tested. Of course there is a possible downside to this; the extra code may make your program run slower. Whether this is significant is a moot point, and will depend to a large extent on the platform and target for your code.

Judicious use of these constraints in your code can leave you satisfied in the correct behaviour and can help identify problem situations early, before they escalate into major problems.

The traditional language mechanism for doing this is the standard C library assert macro. Any programmer who knows a for from a while knows that assert is a simple macro used to enforce a run time constraint in the manner described above.

Another mechanism used to aid the debugging process is logging - for example the Win32 RETAILMSG system, or the Unix syslog. Good logging mechanisms allow us to trace execution, report program state, and are flexible enough to allow us to divert output to different destinations, perhaps also prioritising the significance of certain messages.

Of course, other good debugging (or bug avoiding) practices are the set of defensive programming techniques. This library and article were inspired by my C Vu Professionalism in Programming column on defensive programming [Goodcliffe]. We won't cover the same ground as in that article.

There are a number of requirements for a good "debugging" library that I worked from:

There are a number of secondary feature requirements I was aiming for:

There are a number of very common constraints traditionally tested for with the assert macro. These cases are:

The library should provide different versions of an assert-like function that makes the intent of the constraints listed above explicit. When you come across something like check_pointer_isnt_null(p-ptrval) it's immediately clear what is meant, instead of something like assert(0 != p-ptrval).

So why write a new debugging library?

There are already a number of other debugging libraries available. However, they don't all fulfil the requirements laid out above. Some don't compile out to nothing in a production build. Some make very heavy use of the pre-processor. Others don't fit naturally into modern C++, or the debugging commands are too intrusive, or they don't read easily in the code. I've yet to find the perfect tool for the job.

Firstly, the dbg library defines a number of debugging levels, used to describe the severity of a constraint. The levels specifically related to constraints are:

The different types of constraint provided by the dbg library are:

void example(int *ptr) { dbg::check_ptr(ptr, DBG_HERE); // [] // do something }

int array[10] int index = 10; dbg::check_bounds(index, array, DBG_HERE); array[index] = 5;

switch (variable) { ... default: { // Should never get here dbg::sentinel(DBG_HERE); } }

switch (variable) { ... case SOMETHING: { dbg::unimplemented( dbg::warning, DBG_HERE); break; // just in case constraint behaviour is // non-fatal } ... }

int i = 5; dbg::assertion(DBG_ASSERTION(i != 6));

The behaviour of the dbg library constraints can be set with dbg::set_assertion_behaviour to be one of:

Constraint activity and the logging output can be enabled/disabled at run time, as well as being compiled out in its entirety.

As well as specifying the assertion_behaviour, you can set an assertion period. This is helpful for constraints that get triggered very frequently. If you set_assertion_period of one second, then no matter how many times a constraint fails, it will only produce output once a second. However, it will produce information on how many times it has really triggered for reference.

The dbg logging support is very flexible. You can attach and detach arbitrary ostreams to/from each different diagnostic level. You can attach any number of ostreams to each level. Initially, std::cerr is attached to the dbg::error and dbg::fatal diagnostic levels.

At any point in your code you can log diagnostic information in the usual C++ ostream style. You just write

dbg::out(dbg::info) "Hello this is some information\n";

There are a number of other neat logging features. For example, you can enable a number of diagnostic prefixes with enable_level_prefix and enable_time_prefix. Doing so would produce output like this:

*** Tue Jul 31 09:37:08 2001: info: sentinel reached 

Well-structured code-bases split code into distinct functional units, like libraries, layers, or separate device drivers. The use of the dbg library can compliment this. For each constraint, you can describe a diagnostic source (e.g. foo_lib) and then at run time enable/disable each source selectively. This allows you to pinpoint diagnostics from only particular sections of your code.

For example if you have a number of device drivers, with one called "disk" and one called "keyboard" then in the first you might write a constraint like

dbg::check_ptr("disk_drv", disk-address);

and in the second

dbg::check_ptr("keyboard_drv", keyboard-event_queue);

Now if the keyboard driver appears to be doing odd things, you can switch on its diagnostics by putting this in your main code:

// Enable the keyboard diagnostics at all levels dbg::enable(dbg::all, "keyboard_drv", true);

The keyboard driver code will now produce diagnostic output, and the constraints will be made active, whilst the disk driver will still have all diagnostics dormant.

This is done by making the constraint utilities real functions, not macros. If you do a build that disables the dbg library, then the functions are replaced by empty inline stubs that optimise away to nothing.

This requires a little template magic to produce a credible ostream substitute class, see the dbg.h header file for details.

Do we really need to avoid macros? I believe that in modern C++ code it makes more sense to see a line like:

dbg::check_ptr(p);

rather than something like:

DBG_CHECK_PTR(p);

It reads naturally - in the same way that standard algorithms express intent so much more clearly than a for loop.

This is one of my annoyances. I can't call the general purpose constraint assert since if someone inadvertently mixes dbg.h with assert.h nasty things happen. This is a perfectly good reason for not wanting all of our constraints to be macros as well.

Perhaps this is a good argument for a scope-respecting pre-processor? :-)

This is perhaps the least satisfactory part of the design. Of course, you could remove the facility and remove the problem altogether, but it is genuinely useful.

The reason I'm not happy with the implementation is that it seems to make production builds grow, since the source is identified as a character string; most optimisers don't seem to be able to remove the string if an inline function doesn't use it. This is very annoying.

Other alternatives to using a string to identify the source would be to use integer source codes - but that would require the programmer to have some kind of shared error code header file - a maintenance nightmare. Alternatively, some source definition object could be created and referenced in each dbg call. For diagnostic sources that can span multiple files, this can become clumsy too - you'd have to declare the object in a header file to share it. That's too intrusive.

I'm open to suggestions on this one.

I've done what I can with the post conditions, but it's still not a full and general post condition implementation. The problem here is with the C++ language itself. In order to create a safe post condition you need to use the RAII idiom [Stroustrup14.4.1]. When you create a class to run the post condition you can't include arbitrary code. You can't even do this with a disgusting macro construct unfortunately.

Perhaps we should all give up and use Eiffel? Either that or be happy writing unsafe code...

This has been mentioned to me as an undesirable feature of the library. I don't personally have a big religious problem with it, and can't see a better way of implementing what this does.

The mechanism used has the overwhelming advantage that it is very simple, and does (on the whole) compile out to nothing.

You have to write:

dbg::trace trace_object(DBG_HERE);

and can't miss out the variable name. If you do, the variable is anonymous and gets destroyed at the same place it is created, rather than when the variable goes out of scope. Unfortunately we have no way of enforcing this in the code, which may lead to confusing results when used incorrectly.

It's a shame, and it should be in the standard IMHO. On platforms without a __FUNCTION__ the diagnostic output is not so helpful.

It's neat to be able to select a "throwing" style assertion, but what happens in code not expecting to have to handle exceptions? It may cause more trouble than it's worth. It's certainly debatable whether dbg exceptions should be caught, since they can be compiled out.

Another assertion_behaviour could be added to break out to the debugger when a constraint is broken.

It's a nice idea, but unfortunately far too platform specific - it would require the library to be ported to each new platform, which is undesirable.

Another approach I investigated was to add an on_assert callback facility akin to atexit. In there you can register your own debugger trap. However, I didn't like this. When the debugger opens, you have to step back through your function, then some internal dbg library logic, before reaching the point of constraint failure - not too neat.

There is an internal dbg library function do_assertion_behaviour. You can set a breakpoint here to get the same effect anyway.

The dbg library logging only currently works for ostreams. It would be nice to extend it to all basic_ostreams.

The dbg library is available along with online documentation from http://cthree.org/dbg/. Future developments will be posted there. The API documentation is available from http://cthree.org/dbg/kdoc/dbg.html.