include/wx/stackwalk.h

   1 ///////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/wx/stackwalk.h
   3 // Purpose:     wxStackWalker and related classes, common part
   4 // Author:      Vadim Zeitlin
   5 // Modified by:
   6 // Created:     2005-01-07
   7 // RCS-ID:      $Id$
   8 // Copyright:   (c) 2004 Vadim Zeitlin <vadim@wxwindows.org>
   9 // Licence:     wxWindows licence
  10 ///////////////////////////////////////////////////////////////////////////////
  11
  12 #ifndef _WX_STACKWALK_H_
  13 #define _WX_STACKWALK_H_
  14
  15 #include "wx/defs.h"
  16
  17 #if wxUSE_STACKWALKER
  18
  19 class WXDLLIMPEXP_BASE wxStackFrame;
  20
  21 // ----------------------------------------------------------------------------
  22 // wxStackFrame: a single stack level
  23 // ----------------------------------------------------------------------------
  24
  25 class WXDLLIMPEXP_BASE wxStackFrameBase
  26 {
  27 private:
  28     // put this inline function here so that it is defined before use
  29     wxStackFrameBase *ConstCast() const
  30         { return wx_const_cast(wxStackFrameBase *, this); }
  31
  32 public:
  33     wxStackFrameBase(size_t level, void *address = NULL)
  34     {
  35         m_level = level;
  36
  37         m_line =
  38         m_offset = 0;
  39
  40         m_address = address;
  41     }
  42
  43     // get the level of this frame (deepest/innermost one is 0)
  44     size_t GetLevel() const { return m_level; }
  45
  46     // return the address of this frame
  47     void *GetAddress() const { return m_address; }
  48
  49
  50     // return the unmangled (if possible) name of the function containing this
  51     // frame
  52     wxString GetName() const { ConstCast()->OnGetName(); return m_name; }
  53
  54     // return the instruction pointer offset from the start of the function
  55     size_t GetOffset() const { ConstCast()->OnGetName(); return m_offset; }
  56
  57     // get the module this function belongs to (not always available)
  58     wxString GetModule() const { ConstCast()->OnGetName(); return m_module; }
  59
  60
  61     // return true if we have the filename and line number for this frame
  62     bool HasSourceLocation() const { return !GetFileName().empty(); }
  63
  64     // return the name of the file containing this frame, empty if
  65     // unavailable (typically because debug info is missing)
  66     wxString GetFileName() const
  67         { ConstCast()->OnGetLocation(); return m_filename; }
  68
  69     // return the line number of this frame, 0 if unavailable
  70     size_t GetLine() const { ConstCast()->OnGetLocation(); return m_line; }
  71
  72
  73     // return the number of parameters of this function (may return 0 if we
  74     // can't retrieve the parameters info even although the function does have
  75     // parameters)
  76     virtual size_t GetParamCount() const { return 0; }
  77
  78     // get the name, type and value (in text form) of the given parameter
  79     //
  80     // any pointer may be NULL
  81     //
  82     // return true if at least some values could be retrieved
  83     virtual bool GetParam(size_t WXUNUSED(n),
  84                           wxString * WXUNUSED(type),
  85                           wxString * WXUNUSED(name),
  86                           wxString * WXUNUSED(value)) const
  87     {
  88         return false;
  89     }
  90
  91
  92     // although this class is not supposed to be used polymorphically, give it
  93     // a virtual dtor to silence compiler warnings
  94     virtual ~wxStackFrameBase() { }
  95
  96 protected:
  97     // hooks for derived classes to initialize some fields on demand
  98     virtual void OnGetName() { }
  99     virtual void OnGetLocation() { }
 100
 101
 102     // fields are protected, not private, so that OnGetXXX() could modify them
 103     // directly
 104     size_t m_level;
 105
 106     wxString m_name,
 107              m_module,
 108              m_filename;
 109
 110     size_t m_line;
 111
 112     void *m_address;
 113     size_t m_offset;
 114 };
 115
 116 // ----------------------------------------------------------------------------
 117 // wxStackWalker: class for enumerating stack frames
 118 // ----------------------------------------------------------------------------
 119
 120 class WXDLLIMPEXP_BASE wxStackWalkerBase
 121 {
 122 public:
 123     // ctor does nothing, use Walk() to walk the stack
 124     wxStackWalkerBase() { }
 125
 126     // dtor does nothing neither but should be virtual
 127     virtual ~wxStackWalkerBase() { }
 128
 129     // enumerate stack frames from the current location, skipping the initial
 130     // number of them (this can be useful when Walk() is called from some known
 131     // location and you don't want to see the first few frames anyhow; also
 132     // notice that Walk() frame itself is not included if skip >= 1)
 133     virtual void Walk(size_t skip = 1) = 0;
 134
 135     // enumerate stack frames from the location of uncaught exception
 136     //
 137     // this version can only be called from wxApp::OnFatalException()
 138     virtual void WalkFromException() = 0;
 139
 140 protected:
 141     // this function must be overrided to process the given frame
 142     virtual void OnStackFrame(const wxStackFrame& frame) = 0;
 143 };
 144
 145 #ifdef __WXMSW__
 146     #include "wx/msw/stackwalk.h"
 147 #elif defined(__UNIX__)
 148     #include "wx/unix/stackwalk.h"
 149 #else
 150     #error "wxStackWalker is not supported, set wxUSE_STACKWALKER to 0"
 151 #endif
 152
 153 #endif // wxUSE_STACKWALKER
 154
 155 #endif // _WX_STACKWALK_H_
 156