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