interface/wx/stackwalk.h

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