interface/stackwalk.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        stackwalk.h
   3 // Purpose:     documentation for wxStackWalker class
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxStackWalker
  11     @wxheader{stackwalk.h}
  12
  13     wxStackWalker allows an application to enumerate, or walk, the stack frames
  14     (the function callstack).
  15     It is mostly useful in only two situations:
  16     inside wxApp::OnFatalException function to
  17     programmatically get the location of the crash and, in debug builds, in
  18     wxApp::OnAssertFailure to report the caller of the failed
  19     assert.
  20
  21     wxStackWalker works by repeatedly calling
  22     the wxStackWalker::OnStackFrame method for each frame in the
  23     stack, so to use it you must derive your own class from it and override this
  24     method.
  25
  26     This class will not return anything except raw stack frame addresses if the
  27     debug information is not available. Under Win32 this means that the PDB file
  28     matching the program being executed should be present. Note that if you use
  29     Microsoft Visual C++ compiler, you can create PDB files even for the programs
  30     built in release mode and it doesn't affect the program size (at least if you
  31     don't forget to add @c /opt:ref option which is suppressed by using
  32     @c /debug linker option by default but should be always enabled for
  33     release builds). Under Unix, you need to compile your program with debugging
  34     information (usually using @c -g compiler and linker options) to get the
  35     file and line numbers information, however function names should be available
  36     even without it. Of course, all this is only @true if you build using a recent
  37     enough version of GNU libc which provides the @c backtrace() function
  38     needed to walk the stack.
  39
  40     @ref overview_debuggingoverview "debugging overview" for how to make it
  41     available.
  42
  43     @library{wxbase}
  44     @category{FIXME}
  45
  46     @seealso
  47     wxStackFrame
  48 */
  49 class wxStackWalker
  50 {
  51 public:
  52     /**
  53         Constructor does nothing, use Walk() to walk the
  54         stack.
  55     */
  56     wxStackWalker();
  57
  58     /**
  59         Destructor does nothing neither but should be virtual as this class is used as
  60         a base one.
  61     */
  62     ~wxStackWalker();
  63
  64     /**
  65         This function must be overrided to process the given frame.
  66     */
  67     void OnStackFrame(const wxStackFrame& frame);
  68
  69     /**
  70         Enumerate stack frames from the current location, skipping the initial
  71         number of them (this can be useful when Walk() is called from some known
  72         location and you don't want to see the first few frames anyhow; also
  73         notice that Walk() frame itself is not included if skip = 1).
  74
  75         Up to @e maxDepth frames are walked from the innermost to the outermost one.
  76     */
  77     void Walk(size_t skip = 1, size_t maxDepth = 200);
  78
  79     /**
  80         Enumerate stack frames from the location of uncaught exception.
  81         This method can only be called from
  82         wxApp::OnFatalException.
  83
  84         Up to @e maxDepth frames are walked from the innermost to the outermost one.
  85     */
  86     void WalkFromException(size_t maxDepth = 200);
  87 };
  88
  89
  90 /**
  91     @class wxStackFrame
  92     @wxheader{stackwalk.h}
  93
  94     wxStackFrame represents a single stack frame, or a single function in the call
  95     stack, and is used exclusively together with
  96     wxStackWalker, see there for a more detailed
  97     discussion.
  98
  99     @library{wxbase}
 100     @category{FIXME}
 101
 102     @seealso
 103     wxStackWalker
 104 */
 105 class wxStackFrame
 106 {
 107 public:
 108     /**
 109         Return the address of this frame.
 110     */
 111     void* GetAddress();
 112
 113     /**
 114         Return the name of the file containing this frame, empty if
 115         unavailable (typically because debug info is missing).
 116
 117         Use HasSourceLocation() to check whether
 118         the file name is available.
 119     */
 120     wxString GetFileName();
 121
 122     /**
 123         Get the level of this frame (deepest/innermost one is 0).
 124     */
 125     size_t GetLevel();
 126
 127     /**
 128         Return the line number of this frame, 0 if unavailable.
 129
 130         @sa GetFileName()
 131     */
 132     size_t GetLine();
 133
 134     /**
 135         Get the module this function belongs to (empty if not available).
 136     */
 137     wxString GetModule();
 138
 139     /**
 140         Return the unmangled (if possible) name of the function containing this
 141         frame.
 142     */
 143     wxString GetName();
 144
 145     /**
 146         Return the return address of this frame.
 147     */
 148     size_t GetOffset();
 149
 150     /**
 151         Get the name, type and value (in text form) of the given parameter.
 152         Any pointer may be @NULL if you're not interested in the corresponding
 153         value.
 154
 155         Return @true if at least some values could be retrieved.
 156
 157         This function currently is only implemented under Win32 and requires a PDB
 158         file.
 159     */
 160     bool GetParam(size_t n, wxString * type, wxString * name,
 161                   wxString * value);
 162
 163     /**
 164         Return the number of parameters of this function (may return 0 if we
 165         can't retrieve the parameters info even although the function does have
 166         parameters).
 167     */
 168     size_t GetParamCount();
 169
 170     /**
 171         Return @true if we have the file name and line number for this frame.
 172     */
 173     bool HasSourceLocation();
 174 };