ACE_Stack_Trace Class Reference

Encapsulate a string representation of a stack trace on supported platforms. Stack traces for code built with optimize=1 (or "Release" configs on Visual Studio) may be misleading (missng frames) due to inlining performed by the compiler, which is indepenent of the inline=0 / inline=1 build option and the __ACE_INLINE__ / ACE_NO_INLINE macros. More...

#include <Stack_Trace.h>

List of all members.

Public Member Functions
	ACE_Stack_Trace (ssize_t starting_frame_offset=0, size_t num_frames=0)
	Grab a snapshot of the current stack trace and hold it for later use.
const char *	c_str () const
	Return buffer as a C-style string.
Static Public Attributes
static const size_t	SYMBUFSIZ = ACE_STACK_TRACE_SYMBUFSIZ
Private Member Functions
void	generate_trace (ssize_t starting_frame_offset, size_t num_frames)
Private Attributes
char	buf_ [SYMBUFSIZ]
size_t	buflen_
Static Private Attributes
static const char	UNSUPPORTED [] = "<stack traces unsupported platform>"
static const char	UNABLE_TO_GET_TRACE [] = "<unable to get trace>"

---

Detailed Description

Encapsulate a string representation of a stack trace on supported platforms. Stack traces for code built with optimize=1 (or "Release" configs on Visual Studio) may be misleading (missng frames) due to inlining performed by the compiler, which is indepenent of the inline=0 / inline=1 build option and the __ACE_INLINE__ / ACE_NO_INLINE macros.

A new conversion character, the question mark, was added to ACE_Log_Msg for stack trace logging. The %? conversion character was added as a convenience so that users need not instantiate an ACE_Stack_Trace instance solely for the purpose of printing it in an ACE logging message. The following are functionally equivalent:

     ACE_DEBUG((LM_DEBUG, "%?")); 

     ACE_Stack_Trace st;
     ACE_DEBUG ((LM_DEBUG, "%s", st.c_str() )); 

These usage examples were shown in $ACE_ROOT/tests/Stack_Trace_Test.cpp.

Note:

The stack trace functionality was currently supported on platforms:

• Any platform using glibc as its runtime library, or where ACE_HAS_EXECINFO_H is defined (this covers Linux and Mac) and gcc version >= 3.3.
• VxWorks, both kernel and RTP
• Solaris
• Windows 32 and 64 bit (Visual C++, excluding WinCE/mobile)

Since stack trace buffer size has limitation(ACE_STACK_TRACE_SYMBUFSIZ), you will not get a complete stack trace if ACE_STACK_TRACE_SYMBUFSIZ value is less than actual stack trace data length. To get a complete stack trace, you need set ACE_STACK_TRACE_SYMBUFSIZ with a larger value that is enough for the stack trace data in your config.h file and rebuild ACE.

Using ACE logging mechanism (%?) to log the stack trace also has ACE_MAXLOGMSGLEN size limitation. To get a complete stack trace, you could use different output method. Following is an example.

        ACE_Stack_Trace st;
        ACE_OS::printf("at [%s]\n", st.c_str());

---

Constructor & Destructor Documentation

ACE_Stack_Trace::ACE_Stack_Trace	(	ssize_t	starting_frame_offset = 0,
		size_t	num_frames = 0
	)			[explicit]

Grab a snapshot of the current stack trace and hold it for later use.

Parameters:

	starting_frame_offset	offset into the array of frames to start printing; 0 is the platform-specific offset for the first frame, positive numbers give less frames, negative give more frames
	num_frames	the number of stack frames to include (0 indicates platform-specific maximum)

---

Member Function Documentation

const char * ACE_Stack_Trace::c_str

(

)

const

Return buffer as a C-style string.

Returns:

C-style string with string representation of stack trace.

Note:

Lifecycle of string follows lifecycle of ACE_Stack_Trace instance.

void ACE_Stack_Trace::generate_trace	(	ssize_t	starting_frame_offset,
		size_t	num_frames
	)			[private]

---

Member Data Documentation

char ACE_Stack_Trace::buf_[SYMBUFSIZ] [private]

size_t ACE_Stack_Trace::buflen_ [private]

const size_t ACE_Stack_Trace::SYMBUFSIZ = ACE_STACK_TRACE_SYMBUFSIZ [static]

const char ACE_Stack_Trace::UNABLE_TO_GET_TRACE = "<unable to get trace>" [static, private]

const char ACE_Stack_Trace::UNSUPPORTED = "<stack traces unsupported platform>" [static, private]

---

The documentation for this class was generated from the following files:

• Stack_Trace.h
• Stack_Trace.cpp