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