Fri Jun 6 00:11:05 UTC 2008 Yan Dai <dai_y@ociweb.com>

1 files changed, 38 insertions, 4 deletions

diff --git a/ACE/ace/Stack_Trace.h b/ACE/ace/Stack_Trace.h
index 4b46f705129..eed01c4e7e8 100644
--- a/ACE/ace/Stack_Trace.h
+++ b/ACE/ace/Stack_Trace.h
@@ -5,9 +5,7 @@
  *
  *  $Id$
  *
- *  @brief  Encapsulate string representation of stack trace.
- *
- *  @author Chris Cleeland <cleeland at ociweb dot com>
+ *  @author Chris Cleeland (cleeland.ociweb.com)
  */
 //=============================================================================
 
@@ -35,6 +33,40 @@
  *  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: 
+ *
+ *  \code
+ *     ACE_DEBUG((LM_DEBUG, "%?")); 
+ *
+ *     ACE_Stack_Trace st;
+ *     ACE_DEBUG ((LM_DEBUG, "%s", st.c_str() )); 
+ *  \endcode
+ *
+ *  These usage examples were shown in $ACE_ROOT/tests/Stack_Trace_Test.cpp.
+ *
+ *  @note The stack trace functionality was currently support on platforms:
+ *        - Any platform using glibc as its runtime library, or where ACE_HAS_EXECINFO_H is defined 
+ *          (this covers Linux and Mac)
+ *        - VxWorks, both kernel and RTP
+ *        - Solaris
+ *        - Windows 32 and 64 bit (not WinCE/mobile)  
+ *
+ *  @note Since stack trace buffer size has limitation(@c ACE_STACK_TRACE_SYMBUFSIZ), you will not 
+ *        get a complete stack trace if @c ACE_STACK_TRACE_SYMBUFSIZ value is less than actual stack 
+ *        trace data length. To get a complete stack trace, you need set @c ACE_STACK_TRACE_SYMBUFSIZ 
+ *        with a larger value in your @c config.h file and rebuild ACE.
+ *
+ *  @note 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.
+ *
+ *  \code
+ *        ACE_Stack_Trace st;
+ *        ACE_OS::printf("at [%s]\n", st.c_str());
+ *  \endcode
  */
 class ACE_Export ACE_Stack_Trace
 {
@@ -42,7 +74,9 @@ public:
   /**
    * @brief Grab a snapshot of the current stack trace and hold it for later use.
    *
-   * @param 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
+   * @param 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
    * @param num_frames the number of stack frames to include (0 indicates platform-specific maximum)
    *
    */