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

... / ...

Commit	Line	Data
	1	/////////////////////////////////////////////////////////////////////////////
	2	// Name: stackwalk.h
	3	// Purpose: interface of wxStackWalker
	4	// Author: wxWidgets team
	5	// RCS-ID: $Id$
	6	// Licence: wxWindows license
	7	/////////////////////////////////////////////////////////////////////////////
	8
	9	/**
	10	@class wxStackWalker
	11
	12	wxStackWalker allows an application to enumerate, or walk, the stack frames
	13	(the function callstack).
	14	It is mostly useful in only two situations:
	15	inside wxApp::OnFatalException function to
	16	programmatically get the location of the crash and, in debug builds, in
	17	wxApp::OnAssertFailure to report the caller of the failed
	18	assert.
	19
	20	wxStackWalker works by repeatedly calling
	21	the wxStackWalker::OnStackFrame 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 @c /opt:ref option which is suppressed by using
	31	@c /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 @c -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 @c backtrace() function
	37	needed to walk the stack.
	38
	39	@ref overview_debuggingoverview "debugging overview" for how to make it
	40	available.
	41
	42	@library{wxbase}
	43	@category{FIXME}
	44
	45	@see wxStackFrame
	46	*/
	47	class wxStackWalker
	48	{
	49	public:
	50	/**
	51	Constructor does nothing, use Walk() to walk the
	52	stack.
	53	*/
	54	wxStackWalker();
	55
	56	/**
	57	Destructor does nothing neither but should be virtual as this class is used as
	58	a base one.
	59	*/
	60	virtual ~wxStackWalker();
	61
	62	/**
	63	This function must be overrided to process the given frame.
	64	*/
	65	void OnStackFrame(const wxStackFrame& frame);
	66
	67	/**
	68	Enumerate stack frames from the current location, skipping the initial
	69	number of them (this can be useful when Walk() is called from some known
	70	location and you don't want to see the first few frames anyhow; also
	71	notice that Walk() frame itself is not included if skip = 1).
	72	Up to @a maxDepth frames are walked from the innermost to the outermost one.
	73	*/
	74	virtual void Walk(size_t skip = 1, size_t maxDepth = 200);
	75
	76	/**
	77	Enumerate stack frames from the location of uncaught exception.
	78	This method can only be called from
	79	wxApp::OnFatalException.
	80	Up to @a maxDepth frames are walked from the innermost to the outermost one.
	81	*/
	82	virtual void WalkFromException(size_t maxDepth = 200);
	83	};
	84
	85
	86
	87	/**
	88	@class wxStackFrame
	89
	90	wxStackFrame represents a single stack frame, or a single function in the call
	91	stack, and is used exclusively together with
	92	wxStackWalker, see there for a more detailed
	93	discussion.
	94
	95	@library{wxbase}
	96	@category{FIXME}
	97
	98	@see wxStackWalker
	99	*/
	100	class wxStackFrame
	101	{
	102	public:
	103	/**
	104	Return the address of this frame.
	105	*/
	106	void* GetAddress() const;
	107
	108	/**
	109	Return the name of the file containing this frame, empty if
	110	unavailable (typically because debug info is missing).
	111	Use HasSourceLocation() to check whether
	112	the file name is available.
	113	*/
	114	wxString GetFileName() const;
	115
	116	/**
	117	Get the level of this frame (deepest/innermost one is 0).
	118	*/
	119	size_t GetLevel() const;
	120
	121	/**
	122	Return the line number of this frame, 0 if unavailable.
	123
	124	@see GetFileName()
	125	*/
	126	size_t GetLine() const;
	127
	128	/**
	129	Get the module this function belongs to (empty if not available).
	130	*/
	131	wxString GetModule() const;
	132
	133	/**
	134	Return the unmangled (if possible) name of the function containing this
	135	frame.
	136	*/
	137	wxString GetName() const;
	138
	139	/**
	140	Return the return address of this frame.
	141	*/
	142	size_t GetOffset() const;
	143
	144	/**
	145	Get the name, type and value (in text form) of the given parameter.
	146	Any pointer may be @NULL if you're not interested in the corresponding
	147	value.
	148	Return @true if at least some values could be retrieved.
	149	This function currently is only implemented under Win32 and requires a PDB
	150	file.
	151	*/
	152	bool GetParam(size_t n, wxString* type, wxString* name,
	153	wxString* value) const;
	154
	155	/**
	156	Return the number of parameters of this function (may return 0 if we
	157	can't retrieve the parameters info even although the function does have
	158	parameters).
	159	*/
	160	virtual size_t GetParamCount() const;
	161
	162	/**
	163	Return @true if we have the file name and line number for this frame.
	164	*/
	165	bool HasSourceLocation() const;
	166	};
	167