/////////////////////////////////////////////////////////////////////////////
-// Name: debug.h
+// Name: wx/debug.h
// Purpose: interface of global functions
// Author: wxWidgets team
// RCS-ID: $Id$
/** @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.
*/
#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.
*/
#define wxCOMPILE_TIME_ASSERT2(condition, message, name)
+/**
+ 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
+ IMPLEMENT_APP().
+
+ By default, assert message boxes are suppressed in release build by
+ IMPLEMENT_APP() which uses this macro. If you don't use IMPLEMENT_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
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.
- 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.
+ 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.
+
+ 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 wxOnAssert( const char* fileName,
- int lineNumber,
- const char* function,
- const char* condition,
- const char* message = NULL );
+ */
+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
+
+ @header{wx/debug.h}
+ */
+void wxSetDefaultAssertHandler();
/**
- 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.
+ 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}
*/
projects / wxWidgets.git / blobdiff