1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
|
/////////////////////////////////////////////////////////////////////////////
// Name: stackwalk.h
// Purpose: interface of wxStackWalker
// Author: wxWidgets team
// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
/**
This is the default value of the wxStackWalker::Walk function.
*/
#define wxSTACKWALKER_MAX_DEPTH (200)
/**
@class wxStackWalker
wxStackWalker allows an application to enumerate, or walk, the stack frames
(the function callstack).
It is mostly useful in only two situations: inside wxApp::OnFatalException
function to programmatically get the location of the crash and, in debug builds,
in wxApp::OnAssertFailure to report the caller of the failed assert.
wxStackWalker works by repeatedly calling the wxStackWalker::OnStackFrame
method for each frame in the stack, so to use it you must derive your own
class from it and override this method.
This class will not return anything except raw stack frame addresses if the
debug information is not available. Under Win32 this means that the PDB file
matching the program being executed should be present.
Note that if you use Microsoft Visual C++ compiler, you can create PDB files
even for the programs built in release mode and it doesn't affect the program
size (at least if you don't forget to add @c /opt:ref option which is suppressed
by using @c /debug linker option by default but should be always enabled for
release builds).
Under Unix, you need to compile your program with debugging information
(usually using @c -g compiler and linker options) to get the file and line
numbers information, however function names should be available even without it.
Of course, all this is only @true if you build using a recent enough version
of GNU libc which provides the @c backtrace() function needed to walk the stack.
See @ref overview_debugging for how to make it available.
@library{wxbase}
@category{debugging}
@see wxStackFrame
*/
class wxStackWalker
{
public:
/**
Constructor does nothing, use Walk() to walk the stack.
*/
wxStackWalker(const char* argv0 = NULL);
/**
Destructor does nothing neither but should be virtual as this class is used as
a base one.
*/
virtual ~wxStackWalker();
/**
Enumerate stack frames from the current location, skipping the initial
number of them (this can be useful when Walk() is called from some known
location and you don't want to see the first few frames anyhow; also
notice that Walk() frame itself is not included if skip = 1).
Up to @a maxDepth frames are walked from the innermost to the outermost one.
It defaults to ::wxSTACKWALKER_MAX_DEPTH.
*/
virtual void Walk(size_t skip = 1, size_t maxDepth = wxSTACKWALKER_MAX_DEPTH);
/**
Enumerate stack frames from the location of uncaught exception.
This method can only be called from wxApp::OnFatalException().
Up to @a maxDepth frames are walked from the innermost to the outermost one.
It defaults to ::wxSTACKWALKER_MAX_DEPTH.
*/
virtual void WalkFromException(size_t maxDepth = wxSTACKWALKER_MAX_DEPTH);
protected:
/**
This function must be overidden to process the given frame.
*/
virtual void OnStackFrame(const wxStackFrame& frame) = 0;
};
/**
@class wxStackFrame
wxStackFrame represents a single stack frame, or a single function in the call
stack, and is used exclusively together with wxStackWalker, see there for a more
detailed discussion.
@library{wxbase}
@category{debugging}
@see wxStackWalker
*/
class wxStackFrame
{
public:
/**
Return the address of this frame.
*/
void* GetAddress() const;
/**
Return the name of the file containing this frame, empty if unavailable
(typically because debug info is missing).
Use HasSourceLocation() to check whether the file name is available.
*/
wxString GetFileName() const;
/**
Get the level of this frame (deepest/innermost one is 0).
*/
size_t GetLevel() const;
/**
Return the line number of this frame, 0 if unavailable.
@see GetFileName()
*/
size_t GetLine() const;
/**
Get the module this function belongs to (empty if not available).
*/
wxString GetModule() const;
/**
Return the unmangled (if possible) name of the function containing this frame.
*/
wxString GetName() const;
/**
Return the return address of this frame.
*/
size_t GetOffset() const;
/**
Get the name, type and value (in text form) of the given parameter.
Any pointer may be @NULL if you're not interested in the corresponding value.
Return @true if at least some values could be retrieved.
This function currently is only implemented under Win32 and requires a PDB file.
*/
virtual bool GetParam(size_t n, wxString* type, wxString* name,
wxString* value) const;
/**
Return the number of parameters of this function (may return 0 if we
can't retrieve the parameters info even although the function does have
parameters).
*/
virtual size_t GetParamCount() const;
/**
Return @true if we have the file name and line number for this frame.
*/
bool HasSourceLocation() const;
};
|
