Document wxMessageQueueError.

[wxWidgets.git] / interface / wx / stackwalk.h

diff --git a/interface/wx/stackwalk.h b/interface/wx/stackwalk.h
index b5caef88c73237ed7a975c5a4a974c284cb80f53..486cdb04c4ee99ecd2ac1d3e0468fb8893f164e7 100644 (file)
--- a/interface/wx/stackwalk.h
+++ b/interface/wx/stackwalk.h
@@ -3,44 +3,46 @@
 // Purpose:     interface of wxStackWalker
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     interface of wxStackWalker
 // Author:      wxWidgets team
 // RCS-ID:      $Id$

-// Licence:     wxWindows license
+// 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).
 /**
     @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.
+    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
 
     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.
-
-    @ref overview_debuggingoverview "debugging overview" for how to make it
-    available.
+    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}
 
     @library{wxbase}

-    @category{FIXME}
+    @category{debugging}

 
     @see wxStackFrame
 */
 
     @see wxStackFrame
 */


@@ -48,38 +50,41 @@ class wxStackWalker
 {
 public:
     /**
 {
 public:
     /**

-        Constructor does nothing, use Walk() to walk the
-        stack.
+        Constructor does nothing, use Walk() to walk the stack.

     */
     */

-    wxStackWalker();
+    wxStackWalker(const char* argv0 = NULL);

 
     /**
         Destructor does nothing neither but should be virtual as this class is used as
         a base one.
     */
 
     /**
         Destructor does nothing neither but should be virtual as this class is used as
         a base one.
     */

-    ~wxStackWalker();
-
-    /**
-        This function must be overrided to process the given frame.
-    */
-    void OnStackFrame(const wxStackFrame& frame);
+    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).
 
     /**
         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.
         Up to @a maxDepth frames are walked from the innermost to the outermost one.

+        It defaults to ::wxSTACKWALKER_MAX_DEPTH.

     */
     */

-    void Walk(size_t skip = 1, size_t maxDepth = 200);
+    virtual void Walk(size_t skip = 1, size_t maxDepth = wxSTACKWALKER_MAX_DEPTH);

 
     /**
         Enumerate stack frames from the location of uncaught exception.
 
     /**
         Enumerate stack frames from the location of uncaught exception.

-        This method can only be called from
-        wxApp::OnFatalException.
+        This method can only be called from wxApp::OnFatalException().
+

         Up to @a maxDepth frames are walked from the innermost to the outermost one.
         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 overrided to process the given frame.

     */
     */

-    void WalkFromException(size_t maxDepth = 200);
+    virtual void OnStackFrame(const wxStackFrame& frame) = 0;

 };
 
 
 };
 
 


@@ -88,12 +93,11 @@ public:
     @class wxStackFrame
 
     wxStackFrame represents a single stack frame, or a single function in the call
     @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.
+    stack, and is used exclusively together with wxStackWalker, see there for a more
+    detailed discussion.

 
     @library{wxbase}
 
     @library{wxbase}

-    @category{FIXME}
+    @category{debugging}

 
     @see wxStackWalker
 */
 
     @see wxStackWalker
 */


@@ -106,10 +110,10 @@ public:
     void* GetAddress() const;
 
     /**
     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.
+        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;
 
     */
     wxString GetFileName() const;
 


@@ -131,8 +135,7 @@ public:
     wxString GetModule() const;
 
     /**
     wxString GetModule() const;
 
     /**

-        Return the unmangled (if possible) name of the function containing this
-        frame.
+        Return the unmangled (if possible) name of the function containing this frame.

     */
     wxString GetName() const;
 
     */
     wxString GetName() const;
 


@@ -143,21 +146,20 @@ public:
 
     /**
         Get the name, type and value (in text form) of the given parameter.
 
     /**
         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.
+        Any pointer may be @NULL if you're not interested in the corresponding value.
+

         Return @true if at least some values could be retrieved.
         Return @true if at least some values could be retrieved.

-        This function currently is only implemented under Win32 and requires a PDB
-        file.
+        This function currently is only implemented under Win32 and requires a PDB file.

     */
     */

-    bool GetParam(size_t n, wxString* type, wxString* name,
-                  wxString* value) const;
+    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).
     */
 
     /**
         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).
     */

-    size_t GetParamCount() const;
+    virtual size_t GetParamCount() const;

 
     /**
         Return @true if we have the file name and line number for this frame.
 
     /**
         Return @true if we have the file name and line number for this frame.