X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/ae3c17b4013e80b99976c750c19fca47729517f6..574be073c070a9bbe81ad68e98187b0b9e82c2df:/interface/wx/debug.h diff --git a/interface/wx/debug.h b/interface/wx/debug.h index 6338b91479..5c446af318 100644 --- a/interface/wx/debug.h +++ b/interface/wx/debug.h @@ -6,15 +6,44 @@ // 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} @@ -22,9 +51,37 @@ #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: @@ -41,8 +98,11 @@ #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() @@ -52,8 +112,10 @@ /** 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} */ @@ -61,11 +123,13 @@ /** 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 ) @@ -77,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 ) @@ -88,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) @@ -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 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 ) @@ -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. + This macro should be used to catch misconfigurations at compile-time. + @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(). + 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 @@ -155,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} @@ -172,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 @@ -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__ - -//@} -