ACE/ace/Stack_Trace.h

   1 // -*- C++ -*-
   2 //=============================================================================
   3 /**
   4  *  @file   Stack_Trace.h
   5  *
   6  *  @author Chris Cleeland (cleeland.ociweb.com)
   7  */
   8 //=============================================================================
   9
  10 #ifndef ACE_STACK_TRACE_H
  11 #define ACE_STACK_TRACE_H
  12
  13 #include /**/ "ace/pre.h"
  14
  15 #include "ace/ACE_export.h"
  16 #include "ace/Basic_Types.h"
  17
  18 # if !defined (ACE_LACKS_PRAGMA_ONCE)
  19 #   pragma once
  20 # endif /* ACE_LACKS_PRAGMA_ONCE */
  21
  22 #  ifndef ACE_STACK_TRACE_SYMBUFSIZ
  23 #    define ACE_STACK_TRACE_SYMBUFSIZ 4096
  24 #  endif
  25
  26 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  27
  28 /**
  29  *  @class ACE_Stack_Trace
  30  *
  31  *  @brief Encapsulate a string representation of a stack trace on supported platforms.
  32  *  Stack traces for code built with optimize=1 (or "Release" configs on Visual
  33  *  Studio) may be misleading (missng frames) due to inlining performed by the
  34  *  compiler, which is indepenent of the inline=0 / inline=1 build option and
  35  *  the __ACE_INLINE__ / ACE_NO_INLINE macros.
  36  *
  37  *  A new conversion character, the question mark, was added to ACE_Log_Msg for stack
  38  *  trace logging. The %? conversion character was added as a convenience so that users
  39  *  need not instantiate an ACE_Stack_Trace instance solely for the  purpose of printing
  40  *  it in an ACE logging message.  The following are functionally equivalent:
  41  *
  42  *  \code
  43  *     ACELIB_DEBUG((LM_DEBUG, "%?"));
  44  *
  45  *     ACE_Stack_Trace st;
  46  *     ACELIB_DEBUG ((LM_DEBUG, "%C", st.c_str() ));
  47  *  \endcode
  48  *
  49  *  These usage examples were shown in $ACE_ROOT/tests/Stack_Trace_Test.cpp.
  50  *
  51  *  @note The stack trace functionality was currently supported on platforms:
  52  *        - Any platform using glibc as its runtime library, or where ACE_HAS_EXECINFO_H is defined
  53  *          (this covers Linux and Mac) and gcc version >= 3.3.
  54  *        - VxWorks, both kernel and RTP
  55  *        - Windows 32 and 64 bit (Visual C++)
  56  *
  57  *  @note Since stack trace buffer size has limitation(@c ACE_STACK_TRACE_SYMBUFSIZ), you will not
  58  *        get a complete stack trace if @c ACE_STACK_TRACE_SYMBUFSIZ value is less than actual stack
  59  *        trace data length. To get a complete stack trace, you need set @c ACE_STACK_TRACE_SYMBUFSIZ
  60  *        with a larger value that is enough for the stack trace data in your @c config.h file
  61  *        and rebuild ACE.
  62  *
  63  *  @note Using ACE logging mechanism (%?) to log the stack trace also has ACE_MAXLOGMSGLEN size limitation.
  64  *        To get a complete stack trace, you could use different output method. Following is an example.
  65  *
  66  *  \code
  67  *        ACE_Stack_Trace st;
  68  *        ACE_OS::printf("at [%s]\n", st.c_str());
  69  *  \endcode
  70  */
  71 class ACE_Export ACE_Stack_Trace
  72 {
  73 public:
  74   /**
  75    * @brief Grab a snapshot of the current stack trace and hold it for later use.
  76    *
  77    * @param starting_frame_offset offset into the array of frames to start printing; 0 is the
  78    *  platform-specific offset for the first frame, positive numbers give less frames, negative give
  79    *  more frames
  80    * @param num_frames the number of stack frames to include (0 indicates platform-specific maximum)
  81    *
  82    */
  83   explicit ACE_Stack_Trace (ssize_t starting_frame_offset = 0, size_t num_frames = 0);
  84
  85   /**
  86    * @brief Return buffer as a C-style string.
  87    * @return C-style string with string representation of stack trace.
  88    * @note Lifecycle of string follows lifecycle of ACE_Stack_Trace instance.
  89    */
  90   const char* c_str() const;
  91
  92   static const size_t SYMBUFSIZ = ACE_STACK_TRACE_SYMBUFSIZ;
  93
  94 private:
  95   char buf_[SYMBUFSIZ];
  96   size_t buflen_;
  97
  98   static const char UNSUPPORTED[];
  99   static const char UNABLE_TO_GET_TRACE[];
 100
 101   void generate_trace (ssize_t starting_frame_offset, size_t num_frames);
 102 };
 103
 104 ACE_END_VERSIONED_NAMESPACE_DECL
 105
 106 #include /**/ "ace/post.h"
 107 #endif /* ACE_STACK_TRACE_H */
 108