Quick Links:

bal | bbl | bdl | bsl

Components

Package balst
[Package Group bal]

Provide a portable facility for obtaining & printing a stack trace. More...

Components

 Component balst_objectfileformat
 

Provide platform-dependent object file format trait definitions.

 Component balst_stacktrace
 

Provide a description of a function-call stack.

 Component balst_stacktraceconfigurationutil
 

Provide utility for global configuration of stack trace.

 Component balst_stacktraceframe
 

Provide an attribute class describing an execution stack frame.

 Component balst_stacktraceprinter
 

Provide an object for streaming the current stack trace.

 Component balst_stacktraceprintutil
 

Provide a single function to perform and print a stack trace.

 Component balst_stacktraceresolver_dwarfreader: PRIVATE
 

Provide mechanism for reading DWARF information from object files.

 Component balst_stacktraceresolver_filehelper: PRIVATE
 

Provide platform-independent file input for stack trace resolvers.

 Component balst_stacktraceresolverimpl_dladdr: PRIVATE
 

Provide functions for resolving a stack trace using dladdr.

 Component balst_stacktraceresolverimpl_elf: PRIVATE
 

Provide a utility to resolve ELF symbols in a stack trace.

 Component balst_stacktraceresolverimpl_windows: PRIVATE
 

Provide resolution of symbols in stack trace for Windows objects.

 Component balst_stacktraceresolverimpl_xcoff: PRIVATE
 

Provide a mechanism to resolve xcoff symbols in a stack trace.

 Component balst_stacktracetestallocator
 

Provide a test allocator that reports the call stack for leaks.

 Component balst_stacktraceutil
 

Provide low-level utilities for obtaining & printing a stack-trace.

Detailed Description

Outline
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.
Generated on Fri Mar 31 2023 13:25:18 for BDE Release 3.115.0.0 Production Release by  doxygen 1.7.1