BDE 4.39.x Production Release
Loading...
Searching...
No Matches
balst.h
Go to the documentation of this file.
1/// @file balst.h
2///
3///
4/// @defgroup balst Package balst
5/// @brief Basic Application Library Stack Trace utilities (balst)
6/// @addtogroup bal
7/// @{
8/// @addtogroup balst
9/// @{
10/// * <a href="#balst-purpose"> Purpose</a>
11/// * <a href="#balst-mnemonic"> Mnemonic </a>
12/// * <a href="#balst-description"> Description </a>
13/// * <a href="#balst-hierarchical-synopsis"> Hierarchical Synopsis </a>
14/// * <a href="#balst-component-synopsis"> Component Synopsis </a>
15/// * <a href="#balst-performance-considerations"> Performance Considerations </a>
16/// * <a href="#balst-usage"> Usage </a>
17/// * <a href="#balst-example-1-streaming-to-ball"> Example 1: Streaming to BALL </a>
18///
19/// # Purpose {#balst-purpose}
20/// Provide a portable facility for obtaining & printing a stack trace.
21///
22/// # Mnemonic {#balst-mnemonic}
23/// Basic Application Library Stack Trace utilities (balst)
24///
25/// # Description {#balst-description}
26/// The 'balst' package provides a facility for obtaining and
27/// printing a stack trace at run time.
28///
29/// ## Hierarchical Synopsis {#balst-hierarchical-synopsis}
30///
31/// The 'balst' package currently has 13 components having 7 levels of physical
32/// dependency. The list below shows the hierarchical ordering of the components.
33/// The order of components within each level is not architecturally significant,
34/// just alphabetical.
35/// @code
36/// 7. balst_stacktraceprinter
37///
38/// 6. balst_stacktraceprintutil
39/// balst_stacktracetestallocator
40///
41/// 5. balst_stacktraceutil
42///
43/// 4. balst_resolverimpl_elf !PRIVATE!
44///
45/// 3. balst_resolver_dwarfreader !PRIVATE!
46/// balst_resolverimpl_dladdr !PRIVATE!
47/// balst_resolverimpl_windows !PRIVATE!
48///
49/// 2. balst_resolver_filehelper !PRIVATE!
50/// balst_stacktrace
51///
52/// 1. balst_objectfileformat
53/// balst_stacktraceconfigurationutil
54/// balst_stacktraceframe
55/// @endcode
56///
57/// ## Component Synopsis {#balst-component-synopsis}
58///
59/// @ref balst_objectfileformat :
60/// Provide platform-dependent object file format trait definitions.
61///
62/// @ref balst_resolver_dwarfreader : !PRIVATE!
63/// Provide mechanism for reading DWARF information from object files.
64///
65/// @ref balst_resolver_filehelper : !PRIVATE!
66/// Provide platform-independent file input for stack trace resolvers.
67///
68/// @ref balst_resolverimpl_dladdr : !PRIVATE!
69/// Provide functions for resolving a stack trace using `dladdr`.
70///
71/// @ref balst_resolverimpl_elf : !PRIVATE!
72/// Provide a utility to resolve ELF symbols in a stack trace.
73///
74/// @ref balst_resolverimpl_windows : !PRIVATE!
75/// Provide resolution of symbols in stack trace for Windows objects.
76///
77/// @ref balst_stacktrace :
78/// Provide a description of a function-call stack.
79///
80/// @ref balst_stacktraceconfigurationutil :
81/// Provide utility for global configuration of stack trace.
82///
83/// @ref balst_stacktraceframe :
84/// Provide an attribute class describing an execution stack frame.
85///
86/// @ref balst_stacktraceprinter :
87/// Provide an object for streaming the current stack trace.
88///
89/// @ref balst_stacktraceprintutil :
90/// Provide a single function to perform and print a stack trace.
91///
92/// @ref balst_stacktracetestallocator :
93/// Provide a test allocator that reports the call stack for leaks.
94///
95/// @ref balst_stacktraceutil :
96/// Provide low-level utilities for obtaining & printing a stack-trace.
97///
98/// ## Performance Considerations {#balst-performance-considerations}
99///
100/// Getting a strack trace through any of the components in this package involves
101/// resolving symbols and possibly line numbers and source file names, all of
102/// which are computationally very expensive, involving a lot of disk access to
103/// debug regions of the executable. If the stack trace is called once when a
104/// program crashes, this is not a problem, but if stack traces are to be called
105/// frequently during execution to monitor program behavior in some way, it is
106/// absolutely prohibitive.
107///
108/// The lowest level of stack trace is not in this package, it is
109/// @ref bsls_stackaddressutil , and it contains the code to walk down the stack and
110/// collect a buffer of 'void *'s which are return addresses from the stack, which
111/// can be obtained very quickly and without doing any disk access, to be
112/// expensively resolved to human-readable format later using
113/// @ref balst_stacktraceutil or the Bloomberg stand-alone program 'showfunc.tsk'.
114///
115/// As an example of this, the component @ref balst_stacktracetestallocator needs to
116/// do a stack trace on every memory allocation. To do a fully-resolved stack
117/// trace each time would be a performance catastrophe. So instead, it does a
118/// fast call to @ref bsls_stackaddressutil on every memory allocation, and saves a
119/// buffer of 'void *'s each time, and then, when it is determined at the end that
120/// any of those allocations were leaked, calls @ref balst_stacktraceutil to resolve
121/// the buffer of 'void *'s corresponding to the leaked allocation into
122/// human-readable output to make a report for the client to read.
123///
124/// ## Usage {#balst-usage}
125///
126/// This section illustrates intended use of this package.
127///
128/// ### Example 1: Streaming to BALL {#balst-example-1-streaming-to-ball}
129///
130/// First, we define a recursive function 'recurseAndPrintStack' that recurses 4
131/// times, then calls '<< StackTracePrinter()' to obtain a stack trace and print
132/// it to 'BALL_LOG_FATAL':
133/// @code
134/// #include <balst_stacktraceprinter.h>
135///
136/// void recurseAndStreamStackDefault()
137/// // Recurse 4 times and print a stack trace to 'BALL_LOG_FATAL'.
138/// {
139/// static int recurseCount = 0;
140///
141/// if (recurseCount++ < 4) {
142/// recurseAndStreamStackDefault();
143/// }
144/// else {
145/// BALL_LOG_FATAL << balst::StackTracePrinter();
146/// }
147/// }
148/// @endcode
149/// which, on Linux, produces the output:
150/// @code
151/// (0): recurseAndStreamStackDefault()+0x5a at 0x407762
152/// source:balst_stacktraceprinter.t.cpp:723 in balst_stacktraceprinter.t
153/// (1): recurseAndStreamStackDefault()+0x27 at 0x40772f
154/// source:balst_stacktraceprinter.t.cpp:725 in balst_stacktraceprinter.t
155/// (2): recurseAndStreamStackDefault()+0x27 at 0x40772f
156/// source:balst_stacktraceprinter.t.cpp:725 in balst_stacktraceprinter.t
157/// (3): recurseAndStreamStackDefault()+0x27 at 0x40772f
158/// source:balst_stacktraceprinter.t.cpp:725 in balst_stacktraceprinter.t
159/// (4): recurseAndStreamStackDefault()+0x27 at 0x40772f
160/// source:balst_stacktraceprinter.t.cpp:725 in balst_stacktraceprinter.t
161/// (5): main+0x1a7 at 0x407a37 source:balst_stacktraceprinter.t.cpp:857 in
162/// balst_stacktraceprinter.t
163/// (6): __libc_start_main+0xf5 at 0x7fab4df69495 in /lib64/libc.so.6
164/// (7): --unknown-- at 0x406205 in balst_stacktraceprinter.t
165/// @endcode
166/// Note that long lines of output here have been hand-wrapped to fit into
167/// comments in this 79-column source file. Also note that if the full path of
168/// the executable or library is too long, only the basename will be displayed,
169/// while if it is short, then the full path will be displayed.
170///
171/// @}
172/** @} */