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