Key Concepts

WARNING : PRE-RELEASE VERSION, NOT OFFICIAL BOOST LIBRARY!!!!
StackTrack is not an official Boost library. It has not been submitted for review as a potential Boost library, although the current intention is to seek review after a stable release with significant positive experience in the Boost community.

Annotation

The use of a StackTrack macro at a specific location in an applications source code to create one or more checkpoints to generate StackTrack events. See boost/stacktrack/annotation.hpp

Checkpoint

A checkpoint is a location in C++ code block which will generate an event when it is reached by a thread of execution. All checkpoints are associated with a specific annotation in the application source code, however in some cases the checkpoint and the annotation may not be at the same location. For example, using BOOST_STACKTRACK_SCOPE(name) establishes two checkpoints, one for scope entry at annotation and one for scope exit which corresponds to any potential exit path (closing brace, return statement, exception, etc.) from the enclosing block.

Event

A StackTrack event is moment at which a thread reaches a checkpoint. For each event, a hit record is created and sent to the sink.

Hit

A hit record is an intstance of a C++ struct (occasionally more than one) which contains the information captured for a specfic event. All hit records contain the items described in the follwing table. Some hits contains additional information, such as whether the hit occurred entering or exiting it's scope and dynamic values to be included in the StackTrack log output.

Item	Description
pid	process id
tid	thread id of thread within process
seq	unique sequence number - shared across process
time	time which hit occurred
scope	scope in which hit occurred

Scope

A scope in StackTrack is a section of C++ code which extends from a StackTrack scope declaration to the end of the block containing that scope. For example, the following function

void foo( int z ) {                 // - __scope__ 
    BOOST_STACKTRACK_SCOPE(foo)     // A  foo  entry __checkpoint__ 
                                    //    foo 
    for( int x = 0; x < z; x++ ) {  //    foo 
        BOOST_STACKTRACK_SCOPE(bar) // B  bar  entry __checkpoint__ 
         bar(x);                    // C  bar  possible foo||bar exit __checkpoint__ 
    }                               // D  bar  exit __checkpoint__ 
}                                   // E  foo  exit __checkpoint__

contains two scopes, foo and bar. There are fourcheckpoints associated with the two scopes. Two are entry checkpoints, which will always be at the lines marked // A and // B. There are also two exit checkpoints, which will usually be hit at lines // D and // E, but may occur elsewhere under certain conditions, such as line // C if bar(x); happened to throw an exception.

Sink

See also the reference documentation for the boost::stacktrack::sink class.