Debugging features

Tracing

As quite a lot is ongoing under CnC hood, you might sometimes be interested in what's actually happening. The C++ API provides a convenient interface to provide debugging output which describes what's happening. You can control what parts to see and which to be quiet about.

You need to include

#include <cnc/cnc_debug.h>

which declares the debugging interface. Debug output can be retrieved for steps, tag-collections and item-collections by calling CnC::debug::trace with the respective collections. To trace our Fibonacci step and the item-collection you could issue the respective calls within the constructor of the context or just after creating the context:

    // enable debug output for steps
    CnC::debug::trace( ctxt.m_steps );
    // also enable debug output for our items
    CnC::debug::trace( ctxt.m_fibs );

when running the program you will see a trace event for every step invocation and for every put/get of items. The trace includes annotations about the successful or unsuccessful completion of the traced operations.

If your application uses more than one step-, tag- or item-collection it will be hard to determine to which collection instance individual entries of the default trace belong. To create a more meaningful trace you can assign names to the individual collections. For this their constructor accepts and optional string argument:

    fib_context()
        : CnC::context< fib_context >(),
          // Initialize each step collection
          m_steps( *this, "fib_step" ),
          // Initialize each tag collection
          m_fibs( *this, "fibs" ),
          // Initialize each item collection
          m_tags( *this, "tags" )

Here is the full example code: samples/fib/fib_trace/fib.h and samples/fib/fib_trace/fib_trace.cpp

Scheduling Statistics

Another interesting feature provides statistics about the internal scheduler. Depending on the availability of dependent items, a step might have been executed to early and needs being replayed when the missing item becomes available. The respective information can be printed when the context is destroyed (in our example when the program terminates). All you need to do is enabling this feature using CnC::debug::collect_scheduler_statistics:

    CnC::debug::collect_scheduler_statistics( ctxt );

In the example samples/fib/fib_stats/fib_stats.cpp we have not placed it into the context's constructor (samples/fib/fib_stats/fib.h), but we could have done so. Of course, it is possible to enable tracing and statistics gathering concurrently.

Next: The Tuners