include/wx/stackwalk.h

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