From a256039a12cb07863c3985f86a869cfb7eb3510e Mon Sep 17 00:00:00 2001 From: Vadim Zeitlin Date: Wed, 19 Jan 2005 01:42:25 +0000 Subject: [PATCH] documented wxStackWalker/Frame git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@31475 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- docs/latex/wx/classes.tex | 2 + docs/latex/wx/stackframe.tex | 126 ++++++++++++++++++++++++++++++++++ docs/latex/wx/stackwalker.tex | 88 ++++++++++++++++++++++++ 3 files changed, 216 insertions(+) create mode 100644 docs/latex/wx/stackframe.tex create mode 100644 docs/latex/wx/stackwalker.tex diff --git a/docs/latex/wx/classes.tex b/docs/latex/wx/classes.tex index cb909c6d5e..4433a530e3 100644 --- a/docs/latex/wx/classes.tex +++ b/docs/latex/wx/classes.tex @@ -297,6 +297,8 @@ \input splitevt.tex \input splitter.tex \input splitpar.tex +\input stackframe.tex +\input stackwalker.tex \input stdpaths.tex \input statbmp.tex \input statbox.tex diff --git a/docs/latex/wx/stackframe.tex b/docs/latex/wx/stackframe.tex new file mode 100644 index 0000000000..0bce56bac2 --- /dev/null +++ b/docs/latex/wx/stackframe.tex @@ -0,0 +1,126 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%% Name: stackframe.tex +%% Purpose: wxStackFrame documentation +%% Author: Vadim Zeitlin +%% Created: 2005-01-19 +%% RCS-ID: $Id$ +%% Copyright: (c) 2005 Vadim Zeitlin +%% License: wxWidgets license +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\section{\class{wxStackFrame}}\label{wxstackframe} + + +wxStackFrame represents a single stack frame, or a single function in the call +stack, and is used exclusively together with +\helpref{wxStackWalker}{wxstackwalker}, see there for a more detailed +discussion. + + +\wxheading{Derived from} + +No base class + +\wxheading{Include files} + + + +Only available if \texttt{wxUSE\_STACKWALKER} is $1$, currently only +implemented for Win32 and Unix versions using recent version of GNU libc. + +\wxheading{See also} + +\helpref{wxStackWalker}{wxstackwalker} + + +\latexignore{\rtfignore{\wxheading{Members}}} + + +\membersection{wxStackFrame::GetAddress}\label{wxstackframegetaddress} + +\constfunc{void*}{GetAddress}{\void} + +Return the address of this frame. + + +\membersection{wxStackFrame::GetFileName}\label{wxstackframegetfilename} + +\constfunc{wxString}{GetFileName}{\void} + +Return the name of the file containing this frame, empty if +unavailable (typically because debug info is missing). + +Use \helpre{HasSourceLocation}{wxstackframehassourcelocation} to check whether +the file name is available. + + +\membersection{wxStackFrame::GetLevel}\label{wxstackframegetlevel} + +\constfunc{size\_t}{GetLevel}{\void} + +Get the level of this frame (deepest/innermost one is $0$). + + +\membersection{wxStackFrame::GetLine}\label{wxstackframegetline} + +\constfunc{size\_t}{GetLine}{\void} + +Return the line number of this frame, $0$ if unavailable. + +\wxheading{See also} + +\helpref{GetFileName}{wxstackframegetfilename} + + +\membersection{wxStackFrame::GetModule}\label{wxstackframegetmodule} + +\constfunc{wxString}{GetModule}{\void} + +Get the module this function belongs to (empty if not available). + + +\membersection{wxStackFrame::GetName}\label{wxstackframegetname} + +\constfunc{wxString}{GetName}{\void} + +Return the unmangled (if possible) name of the function containing this +frame. + + +\membersection{wxStackFrame::GetOffset}\label{wxstackframegetoffset} + +\constfunc{size\_t}{GetOffset}{\void} + +Return the return address of this frame. + + +\membersection{wxStackFrame::GetParam}\label{wxstackframegetparam} + +\constfunc{bool}{GetParam}{\param{size\_t }{n}, \param{wxString * }{type}, \param{wxString * }{name}, \param{wxString * }{value}} + +Get the name, type and value (in text form) of the given parameter. +Any pointer may be \textt{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. + + +\membersection{wxStackFrame::GetParamCount}\label{wxstackframegetparamcount} + +\constfunc{size\_t}{GetParamCount}{\void} + +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). + + +\membersection{wxStackFrame::HasSourceLocation}\label{wxstackframehassourcelocation} + +\constfunc{bool}{HasSourceLocation}{\void} + +Return \true if we have the file name and line number for this frame. + + diff --git a/docs/latex/wx/stackwalker.tex b/docs/latex/wx/stackwalker.tex new file mode 100644 index 0000000000..93e12f6432 --- /dev/null +++ b/docs/latex/wx/stackwalker.tex @@ -0,0 +1,88 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%% Name: stackwalker.tex +%% Purpose: wxStackWalker documentation +%% Author: Vadim Zeitlin +%% Created: 2005-01-19 +%% RCS-ID: $Id$ +%% Copyright: (c) 2005 Vadim Zeitlin +%% License: wxWidgets license +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\section{\class{wxStackWalker}}\label{wxstackwalker} + +wxStackWalker allows to enumerate, or walk, the stack frames or, in other +words, the functions callstack. It is mostly useful in only two situations: +inside \helpref{wxApp::OnFatalException}{wxapponfatalexception} function to +programmatically get the location of the crash and, in debug builds, in +\helpref{wxApp::OnAssert}{wxapponassert} to report the caller of the failed +assert. + +wxStackWalker works by repeatedly calling +\helpref{OnStackFrame}{wxstackwalkeronstackframe} 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. See +\helpref{debugging overview}{debuggingoverview} for how to make it available. + +\wxheading{Derived from} + +No base class + +\wxheading{Include files} + + + +Only available if \texttt{wxUSE\_STACKWALKER} is $1$, currently only +implemented for Win32 and Unix versions using recent version of GNU libc. + +\wxheading{See also} + +\helpref{wxStackFrame}{wxstackframe} + + +\latexignore{\rtfignore{\wxheading{Members}}} + + +\membersection{wxStackWalker::wxStackWalker}\label{wxstackwalkerwxstackwalker} + +\func{}{wxStackWalker}{\void} + +Constructor does nothing, use \helpref{Walk()}{wxstackwalkerwalk} to walk the +stack. + + +\membersection{wxStackWalker::\destruct{wxStackWalker}}\label{wxstackwalkerdtor} + +\func{}{\destruct{wxStackWalker}}{\void} + +Destructor does nothing neither but should be virtual as this class is used as +a base one. + + +\membersection{wxStackWalker::OnStackFrame}\label{wxstackwalkeronstackframe} + +\func{void}{OnStackFrame}{\param{const wxStackFrame\& }{frame}} + +This function must be overrided to process the given frame. + + +\membersection{wxStackWalker::Walk}\label{wxstackwalkerwalk} + +\func{void}{Walk}{\param{size\_t }{skip = 1}} + +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 $\ge 1$). + + +\membersection{wxStackWalker::WalkFromException}\label{wxstackwalkerwalkfromexception} + +\func{void}{WalkFromException}{\void} + +Enumerate stack frames from the location of uncaught exception. +This method can only be called from +\helpref{wxApp::OnFatalException()}{wxapponfatalexception}. + -- 2.45.2