balst.txt
@PURPOSE: Provide a portable facility for obtaining & printing a stack trace.
@MNEMONIC: Basic Application Library Stack Trace utilities (balst)
@DESCRIPTION: The 'balst' package provides a facility for obtaining and
printing a stack trace at run time.
/Hierarchical Synopsis
/---------------------
The 'balst' package currently has 14 components having 7 levels of physical
dependency. The list below shows the hierarchical ordering of the components.
The order of components within each level is not architecturally significant,
just alphabetical.
..
7. balst_stacktraceprinter
6. balst_stacktraceprintutil
balst_stacktracetestallocator
5. balst_stacktraceutil
4. balst_stacktraceresolverimpl_elf !PRIVATE!
3. balst_stacktraceresolver_dwarfreader !PRIVATE!
balst_stacktraceresolverimpl_dladdr !PRIVATE!
balst_stacktraceresolverimpl_windows !PRIVATE!
balst_stacktraceresolverimpl_xcoff !PRIVATE!
2. balst_stacktrace
balst_stacktraceresolver_filehelper !PRIVATE!
1. balst_objectfileformat
balst_stacktraceconfigurationutil
balst_stacktraceframe
..
/Component Synopsis
/------------------
: 'balst_objectfileformat':
: Provide platform-dependent object file format trait definitions.
:
: 'balst_stacktrace':
: Provide a description of a function-call stack.
:
: 'balst_stacktraceconfigurationutil':
: Provide utility for global configuration of stack trace.
:
: 'balst_stacktraceframe':
: Provide an attribute class describing an execution stack frame.
:
: 'balst_stacktraceprinter':
: Provide an object for streaming the current stack trace.
:
: 'balst_stacktraceprintutil':
: Provide a single function to perform and print a stack trace.
:
: 'balst_stacktraceresolver_dwarfreader': !PRIVATE!
: Provide mechanism for reading DWARF information from object files.
:
: 'balst_stacktraceresolver_filehelper': !PRIVATE!
: Provide platform-independent file input for stack trace resolvers.
:
: 'balst_stacktraceresolverimpl_dladdr': !PRIVATE!
: Provide functions for resolving a stack trace using 'dladdr'.
:
: 'balst_stacktraceresolverimpl_elf': !PRIVATE!
: Provide a utility to resolve ELF symbols in a stack trace.
:
: 'balst_stacktraceresolverimpl_windows': !PRIVATE!
: Provide resolution of symbols in stack trace for Windows objects.
:
: 'balst_stacktraceresolverimpl_xcoff': !PRIVATE!
: Provide a mechanism to resolve xcoff symbols in a stack trace.
:
: 'balst_stacktracetestallocator':
: Provide a test allocator that reports the call stack for leaks.
:
: 'balst_stacktraceutil':
: Provide low-level utilities for obtaining & printing a stack-trace.
/Performance Considerations
/--------------------------
Getting a strack trace through any of the components in this package involves
resolving symbols and possibly line numbers and source file names, all of
which are computationally very expensive, involving a lot of disk access to
debug regions of the executable. If the stack trace is called once when a
program crashes, this is not a problem, but if stack traces are to be called
frequently during execution to monitor program behavior in some way, it is
absolutely prohibitive.
The lowest level of stack trace is not in this package, it is
'bsls_stackaddressutil', and it contains the code to walk down the stack and
collect a buffer of 'void *'s which are return addresses from the stack, which
can be obtained very quickly and without doing any disk access, to be
expensively resolved to human-readable format later using
'balst_stacktraceutil' or the Bloomberg stand-alone program 'showfunc.tsk'.
As an example of this, the component 'balst_stacktracetestallocator' needs to
do a stack trace on every memory allocation. To do a fully-resolved stack
trace each time would be a performance catastrophe. So instead, it does a
fast call to 'bsls_stackaddressutil' on every memory allocation, and saves a
buffer of 'void *'s each time, and then, when it is determined at the end that
any of those allocations were leaked, calls 'balst_stacktraceutil' to resolve
the buffer of 'void *'s corresponding to the leaked allocation into
human-readable output to make a report for the client to read.
/Usage
/-----
This section illustrates intended use of this package.
/Example 1: Streaming to BALL
/ - - - - - - - - - - - - - -
First, we define a recursive function 'recurseAndPrintStack' that recurses 4
times, then calls '<< StackTracePrinter()' to obtain a stack trace and print
it to 'BALL_LOG_FATAL':
..
#include <balst_stacktraceprinter.h>
void recurseAndStreamStackDefault()
// Recurse 4 times and print a stack trace to 'BALL_LOG_FATAL'.
{
static int recurseCount = 0;
if (recurseCount++ < 4) {
recurseAndStreamStackDefault();
}
else {
BALL_LOG_FATAL << balst::StackTracePrinter();
}
}
..
which, on Linux, produces the output:
..
(0): recurseAndStreamStackDefault()+0x5a at 0x407762
source:balst_stacktraceprinter.t.cpp:723 in balst_stacktraceprinter.t
(1): recurseAndStreamStackDefault()+0x27 at 0x40772f
source:balst_stacktraceprinter.t.cpp:725 in balst_stacktraceprinter.t
(2): recurseAndStreamStackDefault()+0x27 at 0x40772f
source:balst_stacktraceprinter.t.cpp:725 in balst_stacktraceprinter.t
(3): recurseAndStreamStackDefault()+0x27 at 0x40772f
source:balst_stacktraceprinter.t.cpp:725 in balst_stacktraceprinter.t
(4): recurseAndStreamStackDefault()+0x27 at 0x40772f
source:balst_stacktraceprinter.t.cpp:725 in balst_stacktraceprinter.t
(5): main+0x1a7 at 0x407a37 source:balst_stacktraceprinter.t.cpp:857 in
balst_stacktraceprinter.t
(6): __libc_start_main+0xf5 at 0x7fab4df69495 in /lib64/libc.so.6
(7): --unknown-- at 0x406205 in balst_stacktraceprinter.t
..
Note that long lines of output here have been hand-wrapped to fit into
comments in this 79-column source file. Also note that if the full path of
the executable or library is too long, only the basename will be displayed,
while if it is short, then the full path will be displayed.