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
ConstCast()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)
GetLevel()45     size_t GetLevel() const { return m_level; }
46 
47     // return the address of this frame
GetAddress()48     void *GetAddress() const { return m_address; }
49 
50 
51     // return the unmangled (if possible) name of the function containing this
52     // frame
GetName()53     wxString GetName() const { ConstCast()->OnGetName(); return m_name; }
54 
55     // return the instruction pointer offset from the start of the function
GetOffset()56     size_t GetOffset() const { ConstCast()->OnGetName(); return m_offset; }
57 
58     // get the module this function belongs to (not always available)
GetModule()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
HasSourceLocation()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)
GetFileName()67     wxString GetFileName() const
68         { ConstCast()->OnGetLocation(); return m_filename; }
69 
70     // return the line number of this frame, 0 if unavailable
GetLine()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)
GetParamCount()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
GetParam(size_t WXUNUSED (n),wxString * WXUNUSED (type),wxString * WXUNUSED (name),wxString * WXUNUSED (value))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
~wxStackFrameBase()95     virtual ~wxStackFrameBase() { }
96 
97 protected:
98     // hooks for derived classes to initialize some fields on demand
OnGetName()99     virtual void OnGetName() { }
OnGetLocation()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
wxStackWalkerBase()125     wxStackWalkerBase() { }
126 
127     // dtor does nothing neither but should be virtual
~wxStackWalkerBase()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 
160