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