<commit_before> 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 12 components having 6 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.
..
  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_stacktraceframe
..

/Component Synopsis
/------------------
: 'balst_objectfileformat':
:      Provide platform-dependent object file format trait definitions.
:
: 'balst_stacktrace':
:      Provide a description of a function-call stack.
:
: 'balst_stacktraceframe':
:      Provide an attribute class describing an execution stack frame.
:
: '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: Printing a Stack Trace to a Stream
/- - - - - - - - - - - - - - - - - - - - - - -
 This example shows how to obtain a stack trace and print it to a stream, all
 by calling just the static function
 'balst_StackTracePrintUtil::printStackTrace'.

 First, we define a recursive function 'recurseAndPrintStack' that recurses to
 the specified 'depth', then calls 'balst_StackTracePrintUtil::printStackTrace'
 to obtain a stack trace and print it to 'cout'.  When we call
 'printStackTrace', neither of the optional arguments corresponding to
 'maxFrames' or 'demanglingPreferredFlag' are supplied; 'maxFrames' defaults to
 at least 1024 (which is more than we need), and 'demanglingPreferredFlag'
 defaults to 'true'.
..
  static
  void recurseAndPrintStack(int *depth)
      // Recurse to the specified 'depth', then print out the stack trace to
      // 'cout'.
  {
      if (--*depth > 0) {
          recurseAndPrintStack(depth);
      }
      else {
          balst_StackTracePrintUtil::printStackTrace(cout);
      }

      ++*depth;   // Prevent compiler from optimizing tail recursion as a
                  // loop.
  }
..
 Then, we call 'recurseAndPrintStack' from the main program.
..
  int main()
  {
      int depth = 5;
      recurseAndPrintStack(&depth);
      assert(5 == depth);
  }
..
 Now, invoking the main program on AIX produces the following output:
..
  (0): BloombergLP::balst_StackTracePrintUtil::.printStackTrace(
       bdl::basic_ostream<char,bdl::char_traits<char> >&,int,bool)+0x170 at
       0x1000a2c8 source:balst_stacktraceprintutil.cpp:52 in
       balst_stacktraceprintutil.t.dbg_
  (1): .recurseAndPrintStack(int*)+0x58 at 0x1000a118
       source:balst_stacktraceprintutil.t.cpp:652 in
       balst_stacktraceprintutil.t.dbg_
  (2): .recurseAndPrintStack(int*)+0x40 at 0x1000a100
       source:balst_stacktraceprintutil.t.cpp:650
       in balst_stacktraceprintutil.t.dbg_
  (3): .recurseAndPrintStack(int*)+0x40 at 0x1000a100
       source:balst_stacktraceprintutil.t.cpp:650 in
       balst_stacktraceprintutil.t.dbg_
  (4): .recurseAndPrintStack(int*)+0x40 at 0x1000a100
       source:balst_stacktraceprintutil.t.cpp:650 in
       balst_stacktraceprintutil.t.dbg_
  (5): .recurseAndPrintStack(int*)+0x40 at 0x1000a100
       source:balst_stacktraceprintutil.t.cpp:650 in
       balst_stacktraceprintutil.t.dbg_
  (6): .main+0x2f4 at 0x10000a4c source:balst_stacktraceprintutil.t.cpp:724
       in balst_stacktraceprintutil.t.dbg_
  (7): .__start+0x6c at 0x1000020c source:crt0main.s in
       balst_stacktraceprintutil.t.dbg_
..
 Finally, we observe the following about the above output to 'cout'.  Notice
 that since the actual output would write each stack trace frame all on a
 single line, and all the lines here were longer than 80 characters, it has
 been manually edited to wrap and have every line be less than 80 columns.
 Also note the program name is truncated to 32 characters in length.
<commit_msg>balst/doc/balst.txt: balst_objectfileformat should've been docced 'private'<commit_after> 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 12 components having 6 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.
..
  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_stacktraceframe
..

/Component Synopsis
/------------------
: 'balst_objectfileformat':                                           !PRIVATE!
:      Provide platform-dependent object file format trait definitions.
:
: 'balst_stacktrace':
:      Provide a description of a function-call stack.
:
: 'balst_stacktraceframe':
:      Provide an attribute class describing an execution stack frame.
:
: '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: Printing a Stack Trace to a Stream
/- - - - - - - - - - - - - - - - - - - - - - -
 This example shows how to obtain a stack trace and print it to a stream, all
 by calling just the static function
 'balst_StackTracePrintUtil::printStackTrace'.

 First, we define a recursive function 'recurseAndPrintStack' that recurses to
 the specified 'depth', then calls 'balst_StackTracePrintUtil::printStackTrace'
 to obtain a stack trace and print it to 'cout'.  When we call
 'printStackTrace', neither of the optional arguments corresponding to
 'maxFrames' or 'demanglingPreferredFlag' are supplied; 'maxFrames' defaults to
 at least 1024 (which is more than we need), and 'demanglingPreferredFlag'
 defaults to 'true'.
..
  static
  void recurseAndPrintStack(int *depth)
      // Recurse to the specified 'depth', then print out the stack trace to
      // 'cout'.
  {
      if (--*depth > 0) {
          recurseAndPrintStack(depth);
      }
      else {
          balst_StackTracePrintUtil::printStackTrace(cout);
      }

      ++*depth;   // Prevent compiler from optimizing tail recursion as a
                  // loop.
  }
..
 Then, we call 'recurseAndPrintStack' from the main program.
..
  int main()
  {
      int depth = 5;
      recurseAndPrintStack(&depth);
      assert(5 == depth);
  }
..
 Now, invoking the main program on AIX produces the following output:
..
  (0): BloombergLP::balst_StackTracePrintUtil::.printStackTrace(
       bdl::basic_ostream<char,bdl::char_traits<char> >&,int,bool)+0x170 at
       0x1000a2c8 source:balst_stacktraceprintutil.cpp:52 in
       balst_stacktraceprintutil.t.dbg_
  (1): .recurseAndPrintStack(int*)+0x58 at 0x1000a118
       source:balst_stacktraceprintutil.t.cpp:652 in
       balst_stacktraceprintutil.t.dbg_
  (2): .recurseAndPrintStack(int*)+0x40 at 0x1000a100
       source:balst_stacktraceprintutil.t.cpp:650
       in balst_stacktraceprintutil.t.dbg_
  (3): .recurseAndPrintStack(int*)+0x40 at 0x1000a100
       source:balst_stacktraceprintutil.t.cpp:650 in
       balst_stacktraceprintutil.t.dbg_
  (4): .recurseAndPrintStack(int*)+0x40 at 0x1000a100
       source:balst_stacktraceprintutil.t.cpp:650 in
       balst_stacktraceprintutil.t.dbg_
  (5): .recurseAndPrintStack(int*)+0x40 at 0x1000a100
       source:balst_stacktraceprintutil.t.cpp:650 in
       balst_stacktraceprintutil.t.dbg_
  (6): .main+0x2f4 at 0x10000a4c source:balst_stacktraceprintutil.t.cpp:724
       in balst_stacktraceprintutil.t.dbg_
  (7): .__start+0x6c at 0x1000020c source:crt0main.s in
       balst_stacktraceprintutil.t.dbg_
..
 Finally, we observe the following about the above output to 'cout'.  Notice
 that since the actual output would write each stack trace frame all on a
 single line, and all the lines here were longer than 80 characters, it has
 been manually edited to wrap and have every line be less than 80 columns.
 Also note the program name is truncated to 32 characters in length.

{'fraction_non_alphanumeric': 0.07271143278380914, 'fraction_numerical': 0.018496180136710897, 'mean_word_length': 3.046366594360087, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 9, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 12, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4097451', 'n_tokens_mistral': 4367, 'n_tokens_neox': 4179, 'n_words': 1522}