dep/ACE_wrappers/ace/Stack_Trace.h

   1 // -*- C++ -*-
   2 //=============================================================================
   3 /**
   4  *  @file   Stack_Trace.h
   5  *
   6  *  $Id: Stack_Trace.h 81926 2008-06-12 14:43:09Z mitza $
   7  *
   8  *  @author Chris Cleeland (cleeland.ociweb.com)
   9  */
  10 //=============================================================================
  11
  12 #ifndef ACE_STACK_TRACE_H
  13 #define ACE_STACK_TRACE_H
  14
  15 #include /**/ "ace/pre.h"
  16
  17 #include "ace/ACE_export.h"
  18 #include "ace/Basic_Types.h"
  19
  20 # if !defined (ACE_LACKS_PRAGMA_ONCE)
  21 #   pragma once
  22 # endif /* ACE_LACKS_PRAGMA_ONCE */
  23
  24 #  ifndef ACE_STACK_TRACE_SYMBUFSIZ
  25 #    define ACE_STACK_TRACE_SYMBUFSIZ 4096
  26 #  endif
  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  *     ACE_DEBUG((LM_DEBUG, "%?"));
  44  *
  45  *     ACE_Stack_Trace st;
  46  *     ACE_DEBUG ((LM_DEBUG, "%s", 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  *        - Solaris
  56  *        - Windows 32 and 64 bit (Visual C++, excluding WinCE/mobile)
  57  *
  58  *  @note Since stack trace buffer size has limitation(@c ACE_STACK_TRACE_SYMBUFSIZ), you will not
  59  *        get a complete stack trace if @c ACE_STACK_TRACE_SYMBUFSIZ value is less than actual stack
  60  *        trace data length. To get a complete stack trace, you need set @c ACE_STACK_TRACE_SYMBUFSIZ
  61  *        with a larger value that is enough for the stack trace data in your @c config.h file
  62  *        and rebuild ACE.
  63  *
  64  *  @note Using ACE logging mechanism (%?) to log the stack trace also has ACE_MAXLOGMSGLEN size limitation.
  65  *        To get a complete stack trace, you could use different output method. Following is an example.
  66  *
  67  *  \code
  68  *        ACE_Stack_Trace st;
  69  *        ACE_OS::printf("at [%s]\n", st.c_str());
  70  *  \endcode
  71  */
  72 class ACE_Export ACE_Stack_Trace
  73 {
  74 public:
  75   /**
  76    * @brief Grab a snapshot of the current stack trace and hold it for later use.
  77    *
  78    * @param starting_frame_offset offset into the array of frames to start printing; 0 is the
  79    *  platform-specific offset for the first frame, positive numbers give less frames, negative give
  80    *  more frames
  81    * @param num_frames the number of stack frames to include (0 indicates platform-specific maximum)
  82    *
  83    */
  84   explicit ACE_Stack_Trace (ssize_t starting_frame_offset = 0, size_t num_frames = 0);
  85
  86   /**
  87    * @brief Return buffer as a C-style string.
  88    * @return C-style string with string representation of stack trace.
  89    * @note Lifecycle of string follows lifecycle of ACE_Stack_Trace instance.
  90    */
  91   const char* c_str() const;
  92
  93   static const size_t SYMBUFSIZ = ACE_STACK_TRACE_SYMBUFSIZ;
  94
  95 private:
  96   char buf_[SYMBUFSIZ];
  97   size_t buflen_;
  98
  99   static const char UNSUPPORTED[];
 100   static const char UNABLE_TO_GET_TRACE[];
 101
 102   void generate_trace (ssize_t starting_frame_offset, size_t num_frames);
 103 };
 104
 105 #include /**/ "ace/post.h"
 106 #endif /* ACE_STACK_TRACE_H */
 107