interface/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     @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     @see wxStackFrame
  47 */
  48 class wxStackWalker
  49 {
  50 public:
  51     /**
  52         Constructor does nothing, use Walk() to walk the
  53         stack.
  54     */
  55     wxStackWalker();
  56
  57     /**
  58         Destructor does nothing neither but should be virtual as this class is used as
  59         a base one.
  60     */
  61     ~wxStackWalker();
  62
  63     /**
  64         This function must be overrided to process the given frame.
  65     */
  66     void OnStackFrame(const wxStackFrame& frame);
  67
  68     /**
  69         Enumerate stack frames from the current location, skipping the initial
  70         number of them (this can be useful when Walk() is called from some known
  71         location and you don't want to see the first few frames anyhow; also
  72         notice that Walk() frame itself is not included if skip = 1).
  73         Up to @a maxDepth frames are walked from the innermost to the outermost one.
  74     */
  75     void Walk(size_t skip = 1, size_t maxDepth = 200);
  76
  77     /**
  78         Enumerate stack frames from the location of uncaught exception.
  79         This method can only be called from
  80         wxApp::OnFatalException.
  81         Up to @a maxDepth frames are walked from the innermost to the outermost one.
  82     */
  83     void WalkFromException(size_t maxDepth = 200);
  84 };
  85
  86
  87
  88 /**
  89     @class wxStackFrame
  90     @wxheader{stackwalk.h}
  91
  92     wxStackFrame represents a single stack frame, or a single function in the call
  93     stack, and is used exclusively together with
  94     wxStackWalker, see there for a more detailed
  95     discussion.
  96
  97     @library{wxbase}
  98     @category{FIXME}
  99
 100     @see wxStackWalker
 101 */
 102 class wxStackFrame
 103 {
 104 public:
 105     /**
 106         Return the address of this frame.
 107     */
 108     void* GetAddress() const;
 109
 110     /**
 111         Return the name of the file containing this frame, empty if
 112         unavailable (typically because debug info is missing).
 113         Use HasSourceLocation() to check whether
 114         the file name is available.
 115     */
 116     wxString GetFileName() const;
 117
 118     /**
 119         Get the level of this frame (deepest/innermost one is 0).
 120     */
 121     size_t GetLevel() const;
 122
 123     /**
 124         Return the line number of this frame, 0 if unavailable.
 125
 126         @see GetFileName()
 127     */
 128     size_t GetLine() const;
 129
 130     /**
 131         Get the module this function belongs to (empty if not available).
 132     */
 133     wxString GetModule() const;
 134
 135     /**
 136         Return the unmangled (if possible) name of the function containing this
 137         frame.
 138     */
 139     wxString GetName() const;
 140
 141     /**
 142         Return the return address of this frame.
 143     */
 144     size_t GetOffset() const;
 145
 146     /**
 147         Get the name, type and value (in text form) of the given parameter.
 148         Any pointer may be @NULL if you're not interested in the corresponding
 149         value.
 150         Return @true if at least some values could be retrieved.
 151         This function currently is only implemented under Win32 and requires a PDB
 152         file.
 153     */
 154     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     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