2 //=============================================================================
6 * @author Chris Cleeland (cleeland.ociweb.com)
8 //=============================================================================
10 #ifndef ACE_STACK_TRACE_H
11 #define ACE_STACK_TRACE_H
13 #include /**/ "ace/pre.h"
15 #include "ace/ACE_export.h"
16 #include "ace/Basic_Types.h"
18 # if !defined (ACE_LACKS_PRAGMA_ONCE)
20 # endif /* ACE_LACKS_PRAGMA_ONCE */
22 # ifndef ACE_STACK_TRACE_SYMBUFSIZ
23 # define ACE_STACK_TRACE_SYMBUFSIZ 4096
26 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
29 * @class ACE_Stack_Trace
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.
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:
43 * ACELIB_DEBUG((LM_DEBUG, "%?"));
46 * ACELIB_DEBUG ((LM_DEBUG, "%C", st.c_str() ));
49 * These usage examples were shown in $ACE_ROOT/tests/Stack_Trace_Test.cpp.
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++)
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
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.
68 * ACE_OS::printf("at [%s]\n", st.c_str());
71 class ACE_Export ACE_Stack_Trace
75 * @brief Grab a snapshot of the current stack trace and hold it for later use.
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
80 * @param num_frames the number of stack frames to include (0 indicates platform-specific maximum)
83 explicit ACE_Stack_Trace (ssize_t starting_frame_offset
= 0, size_t num_frames
= 0);
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.
90 const char* c_str() const;
92 static const size_t SYMBUFSIZ
= ACE_STACK_TRACE_SYMBUFSIZ
;
98 static const char UNSUPPORTED
[];
99 static const char UNABLE_TO_GET_TRACE
[];
101 void generate_trace (ssize_t starting_frame_offset
, size_t num_frames
);
104 ACE_END_VERSIONED_NAMESPACE_DECL
106 #include /**/ "ace/post.h"
107 #endif /* ACE_STACK_TRACE_H */