X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/76e9224eb2edea8afe45faa6a1cd1b2894d245c2..5b88a837ba75928cd3835a6b97ae2bf5ad983a6e:/interface/wx/debug.h

diff --git a/interface/wx/debug.h b/interface/wx/debug.h
index 0f5a147b6e..5c446af318 100644
--- a/interface/wx/debug.h
+++ b/interface/wx/debug.h
@@ -6,25 +6,83 @@
 // 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.
+
     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}
 */
 #define wxASSERT( condition )
 
+/**
+    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:
 
     @code
@@ -43,6 +101,9 @@
     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()
 
     @header{wx/debug.h}
@@ -53,6 +114,9 @@
     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.
 
+    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( condition, retValue )
@@ -63,6 +127,9 @@
 
     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 )
@@ -74,6 +141,9 @@
 
     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 )
@@ -85,6 +155,9 @@
     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)
@@ -93,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 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 )
@@ -118,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.
 
+    This macro should be used to catch misconfigurations at compile-time.
+
     @see wxASSERT_MSG(), wxASSERT_MIN_BITSIZE()
 
     @header{wx/debug.h}
@@ -130,19 +208,38 @@
     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)
 
 /**
-    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}
 */
-#define wxFAIL()
+#define wxFAIL
 
 /**
     Will always generate an assert error with specified message if this code is
@@ -152,6 +249,9 @@
     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}
@@ -169,23 +269,38 @@
 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}
-*/
-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
@@ -199,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__
-
-//@}
-