Stacktrack stores data as a sequence of fixed size binary buffers, instances of boost::stacktrack::raw_event. The format of these buffers is defined in boost/stacktrack/event.hpp. Each buffer contains

    flags_t         _entryFlags;    ///< combination of FLAGS used to interpret payload 
    st_pid_t        _pid;           ///< process ID 
    sequence_t      _sequence;      ///< sequence number  
    payload_t        payload;       ///< here's the beef 
    

where payload_t is a discriminated union, selected on buffer._entryFlags & boost::stacktrack::raw_event::TYPE_MASK.

Context by PID

Most buffers make reference to additional context defined by earlier buffer entries. Full processing requires collecting and maintaining this context in order to interpret later buffers. All such context is considered local to a specific process, identified by buffer._pid. It is also expected that for a given pid, buffers will be read and processed in the same order in which they were originally captured.

Sequence Count

All buffers carry a sequence count in buffer._sequence. There are a few payload types (PROLOGUE, TIMETYPE, and TIMEINFO) which are not associated with a specific checkpoint, and should always have a sequence number of zero. All other buffers are created as StackTrack passes a specific checkpoint. They will be marked with the value of the sequence count at the time the checkpoint was entered. It is possible for one checkpoint entry to generate multiple buffers, in which case they will share the same sequence number. Comparing sequence counts is the most reliable way to correlate the timing of checkpoints on different threads within a process.

Time

Time is stored in the type boost::stacktrack::detail::raw_hitime_t, which is an opaque, platform specific format. Stacktrack typically will store time values as directly as possible, with no conversions or adjustment. In order to make convenient use of time values, three things may need to happen in postprocessing:

The actual steps vary based on the specifics of the platform's boost::stacktrack::detail::raw_hitime_t implementation. However, there are two payload types which may be used to attempt dynamic interpretation of time values. TIMETYPE provides the divisor used to convert from the numeric form to seconds. TIMEINFO provides a relative raw time value and the corresponding ctime value (seconds since epoch as long), which can establish the necessary offset (+/- 1 second)

Write Counts

Some payloads contain a writeCount member. The write count is used to determine when the output for a given checkpoint needs to include additional context (such as the checkpoint's SOURCELOC). Typically this only occurs the first time a checkpoint is output, and further hits on that checkpoint expect the postprocessing to maintain the context. However, this does pose some difficulties for use cases in which the entire set of buffers since the process started may not be available. To address this issue, when a StackTrack monitored application calls boost::stacktrack::sink_control::next_cycle(), the internal write count is incremented, which will cause each checkpoint to repost the additional context the next time it is encountered. Complete interpretation of buffers is therefore possible as long as there is a full record of buffers since the last cycle increment.

INFO Buffers

Some payload types may need to record additional information whose size is not known until runtime. Stacktrack accomplishes this by converting such information to a series of INFO buffers following the original buffer (all with the same sequence count). If a buffer has INFO buffers following, buffer._entryFlags & boost::stacktrack::HAS_INFO will be true, and the buffer will be followed by a series of INFO buffers, with buffer._entryFlags & boost::stacktrack::INFO_END true for the last buffer. The INFO buffers should always be in order, but other buffers (with a different sequence count) may be interleaved with the series of INFO buffers.

The various payload formats are defined as follows:

/*BOOST_STACKTRACK_EVT_TYPE( TAG, name, description of type,                           */ \ 
/*  BOOST_STACKTRACK_EVT_FLD( type,     name,       description of member              */ \ 
/*)                                                                                    */ \ 
  BOOST_STACKTRACK_EVT_TYPE( HIT, hit, ev_hit captures basic entry/exit/step data,        \ 
    BOOST_STACKTRACK_EVT_FLD( hitime_t, when,       when the hit occured )                \ 
    BOOST_STACKTRACK_EVT_FLD( scopex_t, scopeIndex, where the hit occured)                \ 
    BOOST_STACKTRACK_EVT_FLD( st_tid_t, tid,        thread in which the hit occured )     \ 
  )                                                                                       \ 
  BOOST_STACKTRACK_EVT_TYPEI( FLOC, fileloc, File Location data, filename,                \ 
    BOOST_STACKTRACK_EVT_FLD( int16,    filenum,        file index)                       \ 
    BOOST_STACKTRACK_EVT_FLD( wcount_t, writeCount,     write count)                      \ 
    BOOST_STACKTRACK_EVT_FLD( int16,    properties,     number of properties)             \ 
  )                                                                                       \ 
  BOOST_STACKTRACK_EVT_TYPEI( FPROPERTY, fproperty,     file properties, prop=value,      \ 
    BOOST_STACKTRACK_EVT_FLD( int16,    filenum,        file index )                      \ 
    BOOST_STACKTRACK_EVT_FLD( wcount_t, writeCount,     write count )                     \ 
    BOOST_STACKTRACK_EVT_FLD( int16,    propertynum,    property index )                  \ 
  )                                                                                       \ 
  BOOST_STACKTRACK_EVT_TYPE( SLOC, sourceloc, source location,                            \ 
    BOOST_STACKTRACK_EVT_FLD( scopex_t, scopeIndex,     scope index )                     \ 
    BOOST_STACKTRACK_EVT_FLD( int16,    style,          scope style )                     \ 
    BOOST_STACKTRACK_EVT_FLD( int16,    linenum,        line number )                     \ 
    BOOST_STACKTRACK_EVT_FLD( wcount_t, writeCount,     write count )                     \ 
    BOOST_STACKTRACK_EVT_FLD( int16,    filenum,        file number )                     \ 
  )                                                                                       \ 
  BOOST_STACKTRACK_EVT_TYPE( PROLOGUE, prologue,  Prologue data,                          \ 
    BOOST_STACKTRACK_EVT_FLD( uns32,    _12345678,      magic identifier )                \ 
    BOOST_STACKTRACK_EVT_FLD( uns32,    version,        stacktrack format version )       \ 
    BOOST_STACKTRACK_EVT_FLD( char,     info_len,       length of _info field )           \ 
    BOOST_STACKTRACK_EVT_FLD( char,     entry_size,     size of entry )                   \ 
    BOOST_STACKTRACK_EVT_FLD( char,     payload_offset, offset of payload in entry )      \ 
  )                                                                                       \ 
  BOOST_STACKTRACK_EVT_TYPE( PROCINFO, procinfo, Process data,                            \ 
    BOOST_STACKTRACK_EVT_FLD( st_pid_t, pid,            proccess ID )                     \ 
    BOOST_STACKTRACK_EVT_FLD( wcount_t, writeCount,     write count )                     \ 
  )                                                                                       \ 
  BOOST_STACKTRACK_EVT_TYPE( TIMEINFO, timeinfo, Time info (start time) data,             \ 
    BOOST_STACKTRACK_EVT_FLD( hitime_t, start_hires,    start time in raw hi-res form )   \ 
    BOOST_STACKTRACK_EVT_FLD( sctime_t, start,          start time in CTIME form )        \ 
  )                                                                                       \ 
  BOOST_STACKTRACK_EVT_TYPE( TIMETYPE, timetype, time conversion data,                    \ 
    BOOST_STACKTRACK_EVT_FLD( hitime_t, tdiv,           time divisor )                    \ 
    BOOST_STACKTRACK_EVT_FLD( uns16,    timetype,       time type )                       \ 
  )                                                                                       \