git.saurik.com Git - wxWidgets.git/blame_incremental

... / ...

Commit	Line	Data
	1	%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
	2	%% Name: stackwalker.tex
	3	%% Purpose: wxStackWalker documentation
	4	%% Author: Vadim Zeitlin
	5	%% Created: 2005-01-19
	6	%% RCS-ID: $Id$
	7	%% Copyright: (c) 2005 Vadim Zeitlin
	8	%% License: wxWindows license
	9	%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
	10
	11	\section{\class{wxStackWalker}}\label{wxstackwalker}
	12
	13	wxStackWalker allows an application to enumerate, or walk, the stack frames (the function callstack).
	14	It is mostly useful in only two situations:
	15	inside \helpref{wxApp::OnFatalException}{wxapponfatalexception} function to
	16	programmatically get the location of the crash and, in debug builds, in
	17	\helpref{wxApp::OnAssertFailure}{wxapponassertfailure} to report the caller of the failed
	18	assert.
	19
	20	wxStackWalker works by repeatedly calling
	21	the \helpref{OnStackFrame}{wxstackwalkeronstackframe} method for each frame in the
	22	stack, so to use it you must derive your own class from it and override this
	23	method.
	24
	25	This class will not return anything except raw stack frame addresses if the
	26	debug information is not available. Under Win32 this means that the PDB file
	27	matching the program being executed should be present. Note that if you use
	28	Microsoft Visual C++ compiler, you can create PDB files even for the programs
	29	built in release mode and it doesn't affect the program size (at least if you
	30	don't forget to add \texttt{/opt:ref} option which is suppressed by using
	31	\texttt{/debug} linker option by default but should be always enabled for
	32	release builds). Under Unix, you need to compile your program with debugging
	33	information (usually using \texttt{-g} compiler and linker options) to get the
	34	file and line numbers information, however function names should be available
	35	even without it. Of course, all this is only true if you build using a recent
	36	enough version of GNU libc which provides the \texttt{backtrace()} function
	37	needed to walk the stack.
	38
	39	\helpref{debugging overview}{debuggingoverview} for how to make it available.
	40
	41	\wxheading{Derived from}
	42
	43	No base class
	44
	45	\wxheading{Include files}
	46
	47	<wx/stackwalk.h>
	48
	49	Only available if \texttt{wxUSE\_STACKWALKER} is $1$, currently only
	50	implemented for Win32 and Unix versions using recent version of GNU libc.
	51
	52	\wxheading{See also}
	53
	54	\helpref{wxStackFrame}{wxstackframe}
	55
	56
	57	\latexignore{\rtfignore{\wxheading{Members}}}
	58
	59
	60	\membersection{wxStackWalker::wxStackWalker}\label{wxstackwalkerwxstackwalker}
	61
	62	\func{}{wxStackWalker}{\void}
	63
	64	Constructor does nothing, use \helpref{Walk()}{wxstackwalkerwalk} to walk the
	65	stack.
	66
	67
	68	\membersection{wxStackWalker::\destruct{wxStackWalker}}\label{wxstackwalkerdtor}
	69
	70	\func{}{\destruct{wxStackWalker}}{\void}
	71
	72	Destructor does nothing neither but should be virtual as this class is used as
	73	a base one.
	74
	75
	76	\membersection{wxStackWalker::OnStackFrame}\label{wxstackwalkeronstackframe}
	77
	78	\func{void}{OnStackFrame}{\param{const wxStackFrame\& }{frame}}
	79
	80	This function must be overrided to process the given frame.
	81
	82
	83	\membersection{wxStackWalker::Walk}\label{wxstackwalkerwalk}
	84
	85	\func{void}{Walk}{\param{size\_t }{skip = 1}}
	86
	87	Enumerate stack frames from the current location, skipping the initial
	88	number of them (this can be useful when Walk() is called from some known
	89	location and you don't want to see the first few frames anyhow; also
	90	notice that Walk() frame itself is not included if skip $\ge 1$).
	91
	92
	93	\membersection{wxStackWalker::WalkFromException}\label{wxstackwalkerwalkfromexception}
	94
	95	\func{void}{WalkFromException}{\void}
	96
	97	Enumerate stack frames from the location of uncaught exception.
	98	This method can only be called from
	99	\helpref{wxApp::OnFatalException()}{wxapponfatalexception}.