/////////////////////////////////////////////////////////////////////////////
-// Name: debug.h
+// Name: wx/debug.h
// Purpose: interface of global functions
// Author: wxWidgets team
// RCS-ID: $Id$
-// Licence: wxWindows license
+// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
-/** @ingroup group_funcmacro_debug */
+/** @addtogroup group_funcmacro_debug */
//@{
+/**
+ @def wxDEBUG_LEVEL
+
+ Preprocessor symbol defining the level of debug support available.
+
+ This symbol is defined to 1 by default meaning that asserts are compiled in
+ (although they may be disabled by a call to wxDisableAsserts()). You may
+ predefine it as 0 prior to including any wxWidgets headers to omit the
+ calls to wxASSERT() and related macros entirely in your own code and you
+ may also predefine it as 0 when building wxWidgets to also avoid including
+ any asserts in wxWidgets itself.
+
+ Alternatively, you may predefine it as 2 to include wxASSERT_LEVEL_2() and
+ similar macros which are used for asserts which have non-trivial run-time
+ costs and so are disabled by default.
+
+ @since 2.9.1
+
+ @header{wx/debug.h}
+ */
+#define wxDEBUG_LEVEL
+
+/**
+ @def __WXDEBUG__
+
+ Compatibility macro indicating presence of debug support.
+
+ This symbol is defined if wxDEBUG_LEVEL is greater than 0 and undefined
+ otherwise.
+
+ @header{wx/debug.h}
+ */
+#define __WXDEBUG__
+
+/**
+ 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 )
/**
- 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:
#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()
/**
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}
*/
/**
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 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 )
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 )
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)
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 )
(@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}
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.
+
+ @since 2.9.0
+
+ @header{wx/debug.h}
+ */
+void wxDisableAsserts();
+
+/**
+ @def wxDISABLE_ASSERTS_IN_RELEASE_BUILD
+
+ Use this macro to disable asserts in release build when not using
+ wxIMPLEMENT_APP().
+
+ By default, assert message boxes are suppressed in release build by
+ wxIMPLEMENT_APP() which uses this macro. If you don't use wxIMPLEMENT_APP()
+ because your application initializes wxWidgets directly (e.g. calls
+ wxEntry() or wxEntryStart() itself) but still want to suppress assert
+ notifications in release build you need to use this macro directly.
+
+ @see wxDISABLE_DEBUG_SUPPORT()
+
+ @since 2.9.1
+
+ @header{wx/debug.h}
+ */
+#define wxDISABLE_ASSERTS_IN_RELEASE_BUILD() 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
reached (in debug mode).
- This macro is useful for marking unreachable" code areas, for example it
+ This macro is useful for marking "unreachable" code areas, for example it
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}
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.
- 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.
+ 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.
- @header{wx/debug.h}
-*/
-void wxOnAssert( const char* fileName,
- int lineNumber,
- const char* function,
- const char* condition,
- const char* message = NULL );
+ 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.
-/**
- In debug mode (when @c __WXDEBUG__ is defined) this function generates a
- debugger exception meaning that the control is passed to the debugger if
- one is attached to the process. Otherwise the program just terminates
- abnormally. In release mode this function does nothing.
+ 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.
+
+ 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.
+
+ @since 2.9.0
@header{wx/debug.h}
-*/
-void wxTrap();
+ */
+wxAssertHandler_t wxSetAssertHandler(wxAssertHandler_t handler);
-//@}
+/**
+ Reset the assert handler to default function which shows a message box when
+ an assert happens.
+ This can be useful for the applications compiled in release build (with @c
+ NDEBUG defined) for which the asserts are by default disabled: if you wish
+ to enable them even in this case you need to call this function.
+ @since 2.9.1
-/** @ingroup group_funcmacro_misc */
-//@{
+ @header{wx/debug.h}
+ */
+void wxSetDefaultAssertHandler();
/**
- 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.
+ Generate a debugger exception meaning that the control is passed to the
+ debugger if one is attached to the process.
+
+ Otherwise the program just terminates abnormally.
+
+ If @c wxDEBUG_LEVEL is 0 (which is not the default) this function does
+ nothing.
@header{wx/debug.h}
*/
-#define __WXFUNCTION__
+void wxTrap();
//@}
projects / wxWidgets.git / blobdiff