undo the last change as it results in buildbot configuration error

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

diff --git a/interface/wx/debug.h b/interface/wx/debug.h
index 6338b9147902b1adfc9995994f0102f1df8729c9..5c446af318dbb5da499e7ddbdee7387c5989fdcf 100644 (file)
--- a/interface/wx/debug.h
+++ b/interface/wx/debug.h
@@ -6,15 +6,44 @@
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 

-/** @ingroup group_funcmacro_debug */
+/** @addtogroup group_funcmacro_debug */

 //@{
 
 //@{
 

+/**
+    @def wxDEBUG_LEVEL
+
+    Preprocessor symbol defining the level of debug support available.
+
+    Currently wxDEBUG_LEVEL is 0 in release builds (__WXDEBUG__ not defined)
+    and 1 in debug builds (it is). In the immediate future this will change
+    however and this symbol will be defined directly as 0, 1 or 2 while
+    __WXDEBUG__ won't be used by wxWidgets any longer.
+
+    @header{wx/debug.h}
+ */
+#define wxDEBUG_LEVEL
+
+/**
+    Type for the function called in case of assert failure.
+
+    @see wxSetAssertHandler()
+ */
+typedef void (*wxAssertHandler_t)(const wxString& file,
+                                  int line,
+                                  const wxString& func,
+                                  const wxString& cond,
+                                  const wxString& msg);
+

 /**
     Assert macro. An error message will be generated if the condition is @false in
     debug mode, but nothing will be done in the release build.
 /**
     Assert macro. An error message will be generated if the condition is @false in
     debug mode, but nothing will be done in the release build.

+

     Please note that the condition in wxASSERT() should have no side effects
     because it will not be executed in release mode at all.
 
     Please note that the condition in wxASSERT() should have no side effects
     because it will not be executed in release mode at all.
 

+    This macro should be used to catch (in debug builds) logical errors done
+    by the programmer.
+

     @see wxASSERT_MSG(), wxCOMPILE_TIME_ASSERT()
 
     @header{wx/debug.h}
     @see wxASSERT_MSG(), wxCOMPILE_TIME_ASSERT()
 
     @header{wx/debug.h}


@@ -22,9 +51,37 @@
 #define wxASSERT( condition )
 
 /**
 #define wxASSERT( condition )
 
 /**

-    This macro results in a
-    @ref overview_wxcompiletimeassert "compile time assertion failure" if the
-    size of the given @c type is less than @c size bits.
+    Assert macro for expensive run-time checks.
+
+    This macro does nothing unless wxDEBUG_LEVEL is 2 or more and is meant to
+    be used for the assertions with noticeable performance impact and which,
+    hence, should be disabled during run-time.
+
+    If wxDEBUG_LEVEL is 2 or more, it becomes the same as wxASSERT().
+
+    @header{wx/debug.h}
+ */
+#define wxASSERT_LEVEL_2( condition )
+
+/**
+    Assert macro with a custom message for expensive run-time checks.
+
+    If wxDEBUG_LEVEL is 2 or more, this is the same as wxASSERT_MSG(),
+    otherwise it doesn't do anything at all.
+
+    @see wxASSERT_LEVEL_2()
+
+    @header{wx/debug.h}
+ */
+#define wxASSERT_LEVEL_2_MSG( condition, msg)
+
+
+/**
+    This macro results in a @ref wxCOMPILE_TIME_ASSERT "compile time assertion failure"
+    if the size of the given @c type is less than @c size bits.
+
+    This macro should be used to catch (in debug builds) logical errors done
+    by the programmer.

 
     You may use it like this, for example:
 
 
     You may use it like this, for example:
 


@@ -41,8 +98,11 @@
 #define wxASSERT_MIN_BITSIZE( type, size )
 
 /**
 #define wxASSERT_MIN_BITSIZE( type, size )
 
 /**

-    Assert macro with message. An error message will be generated if the
-    condition is @false.
+    Assert macro with message.
+    An error message will be generated if the condition is @false.
+
+    This macro should be used to catch (in debug builds) logical errors done
+    by the programmer.

 
     @see wxASSERT(), wxCOMPILE_TIME_ASSERT()
 
 
     @see wxASSERT(), wxCOMPILE_TIME_ASSERT()
 


@@ -52,8 +112,10 @@
 
 /**
     Checks that the condition is @true, returns with the given return value if
 
 /**
     Checks that the condition is @true, returns with the given return value if

-    not (stops execution in debug mode). This check is done even in release
-    mode.
+    not (stops execution in debug mode). This check is done even in release mode.
+
+    This macro should be used to catch (both in debug and release builds) logical
+    errors done by the programmer.

 
     @header{wx/debug.h}
 */
 
     @header{wx/debug.h}
 */


@@ -61,11 +123,13 @@
 
 /**
     Checks that the condition is @true, returns with the given return value if
 
 /**
     Checks that the condition is @true, returns with the given return value if

-    not (stops execution in debug mode). This check is done even in release
-    mode.
+    not (stops execution in debug mode). This check is done even in release mode.

 
     This macro may be only used in non-void functions, see also wxCHECK_RET().
 
 
     This macro may be only used in non-void functions, see also wxCHECK_RET().
 

+    This macro should be used to catch (both in debug and release builds) logical
+    errors done by the programmer.
+

     @header{wx/debug.h}
 */
 #define wxCHECK_MSG( condition, retValue, message )
     @header{wx/debug.h}
 */
 #define wxCHECK_MSG( condition, retValue, message )


@@ -77,6 +141,9 @@
 
     This macro should be used in void functions instead of wxCHECK_MSG().
 
 
     This macro should be used in void functions instead of wxCHECK_MSG().
 

+    This macro should be used to catch (both in debug and release builds) logical
+    errors done by the programmer.
+

     @header{wx/debug.h}
 */
 #define wxCHECK_RET( condition, message )
     @header{wx/debug.h}
 */
 #define wxCHECK_RET( condition, message )


@@ -88,6 +155,9 @@
     function must be done when the @c condition is @false. This check is done
     even in release mode.
 
     function must be done when the @c condition is @false. This check is done
     even in release mode.
 

+    This macro should be used to catch (both in debug and release builds) logical
+    errors done by the programmer.
+

     @header{wx/debug.h}
 */
 #define wxCHECK2(condition, operation)
     @header{wx/debug.h}
 */
 #define wxCHECK2(condition, operation)


@@ -96,6 +166,9 @@
     This is the same as wxCHECK2(), but wxFAIL_MSG() with the specified
     @c message is called instead of wxFAIL() if the @c condition is @false.
 
     This is the same as wxCHECK2(), but wxFAIL_MSG() with the specified
     @c message is called instead of wxFAIL() if the @c condition is @false.
 

+    This macro should be used to catch (both in debug and release builds) logical
+    errors done by the programmer.
+

     @header{wx/debug.h}
 */
 #define wxCHECK2_MSG( condition, operation, message )
     @header{wx/debug.h}
 */
 #define wxCHECK2_MSG( condition, operation, message )


@@ -121,6 +194,8 @@
     (@c /ZI) option, so you shouldn't use it ('Program Database' (@c /Zi) is ok
     though) for the code making use of this macro.
 
     (@c /ZI) option, so you shouldn't use it ('Program Database' (@c /Zi) is ok
     though) for the code making use of this macro.
 

+    This macro should be used to catch misconfigurations at compile-time.
+

     @see wxASSERT_MSG(), wxASSERT_MIN_BITSIZE()
 
     @header{wx/debug.h}
     @see wxASSERT_MSG(), wxASSERT_MIN_BITSIZE()
 
     @header{wx/debug.h}


@@ -133,19 +208,38 @@
     macro to avoid getting the compilation errors described for
     wxCOMPILE_TIME_ASSERT().
 
     macro to avoid getting the compilation errors described for
     wxCOMPILE_TIME_ASSERT().
 

+    This macro should be used to catch misconfigurations at compile-time.
+

     @header{wx/debug.h}
 */
 #define wxCOMPILE_TIME_ASSERT2(condition, message, name)
 
 /**
     @header{wx/debug.h}
 */
 #define wxCOMPILE_TIME_ASSERT2(condition, message, name)
 
 /**

-    Will always generate an assert error if this code is reached (in debug
-    mode).
+    Disable the condition checks in the assertions.
+
+    This is the same as calling wxSetAssertHandler() with @NULL handler.
+ */
+void wxDisableAsserts();
+
+/**
+    Will always generate an assert error if this code is reached (in debug mode).
+    Note that you don't have to (and cannot) use brackets when invoking this
+    macro:
+
+    @code
+        if (...some condition...) {
+            wxFAIL;
+        }
+    @endcode
+
+    This macro should be used to catch (in debug builds) logical errors done
+    by the programmer.

 
     @see wxFAIL_MSG()
 
     @header{wx/debug.h}
 */
 
     @see wxFAIL_MSG()
 
     @header{wx/debug.h}
 */

-#define wxFAIL()
+#define wxFAIL

 
 /**
     Will always generate an assert error with specified message if this code is
 
 /**
     Will always generate an assert error with specified message if this code is


@@ -155,6 +249,9 @@
     may be used in the "default:" branch of a switch statement if all possible
     cases are processed above.
 
     may be used in the "default:" branch of a switch statement if all possible
     cases are processed above.
 

+    This macro should be used to catch (in debug builds) logical errors done
+    by the programmer.
+

     @see wxFAIL()
 
     @header{wx/debug.h}
     @see wxFAIL()
 
     @header{wx/debug.h}


@@ -172,23 +269,38 @@
 bool wxIsDebuggerRunning();
 
 /**
 bool wxIsDebuggerRunning();
 
 /**

-    This function is called whenever one of debugging macros fails (i.e.
-    condition is @false in an assertion). It is only defined in the debug mode,
-    in release builds the wxCHECK() failures don't result in anything.
+    Sets the function to be called in case of assertion failure.
+
+    The default assert handler forwards to wxApp::OnAssertFailure() whose
+    default behaviour is, in turn, to show the standard assertion failure
+    dialog if a wxApp object exists or shows the same dialog itself directly
+    otherwise.
+
+    While usually it is enough -- and more convenient -- to just override
+    OnAssertFailure(), to handle all assertion failures, including those
+    occurring even before wxApp object creation of after its destruction you
+    need to provide your assertion handler function.
+
+    This function also provides a simple way to disable all asserts: simply
+    pass @NULL pointer to it. Doing this will result in not even evaluating
+    assert conditions at all, avoiding almost all run-time cost of asserts.

 
 

-    To override the default behaviour in the debug builds which is to show the
-    user a dialog asking whether he wants to abort the program, continue or
-    continue ignoring any subsequent assert failures, you may override
-    wxApp::OnAssertFailure() which is called by this function if the global
-    application object exists.
+    Notice that this function is not MT-safe, so you should call it before
+    starting any other threads.
+
+    The return value of this function is the previous assertion handler. It can
+    be called after any pre-processing by your handler and can also be restored
+    later if you uninstall your handler.
+
+    @param handler
+        The function to call in case of assertion failure or @NULL.
+    @return
+        The previous assert handler which is not @NULL by default but could be
+        @NULL if it had been previously set to this value using this function.

 
     @header{wx/debug.h}
 
     @header{wx/debug.h}

-*/
-void wxOnAssert( const char* fileName,
-                  int lineNumber,
-                  const char* function,
-                  const char* condition,
-                  const char* message = NULL );
+ */
+wxAssertHandler_t wxSetAssertHandler(wxAssertHandler_t handler);

 
 /**
     In debug mode (when @c __WXDEBUG__ is defined) this function generates a
 
 /**
     In debug mode (when @c __WXDEBUG__ is defined) this function generates a


@@ -202,19 +314,3 @@ void wxTrap();
 
 //@}
 
 
 //@}
 

-
-
-/** @ingroup group_funcmacro_misc */
-//@{
-
-/**
-    This macro expands to the name of the current function if the compiler
-    supports any of @c __FUNCTION__, @c __func__ or equivalent variables or
-    macros or to @NULL if none of them is available.
-
-    @header{wx/debug.h}
-*/
-#define __WXFUNCTION__
-
-//@}
-