X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/76e9224eb2edea8afe45faa6a1cd1b2894d245c2..7344108e8a129a3f9b4df5ab0f98a1713db03b89:/interface/wx/debug.h diff --git a/interface/wx/debug.h b/interface/wx/debug.h index 0f5a147b6e..7e787e88c4 100644 --- a/interface/wx/debug.h +++ b/interface/wx/debug.h @@ -1,30 +1,119 @@ ///////////////////////////////////////////////////////////////////////////// -// 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 */ //@{ +/** + Exits the program immediately. + + This is a simple wrapper for the standard abort() function which is not + available under all platforms (currently only Windows CE doesn't provide + it). + + @since 2.9.4 + */ +void wxAbort(); + +/** + @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 ) +/** + 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 +132,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 +145,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 +158,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 +172,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 +186,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 +197,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 +225,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,28 +239,74 @@ 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} @@ -162,56 +317,74 @@ Returns @true if the program is running under debugger, @false otherwise. Please note that this function is currently only implemented for Win32 and - Mac builds using CodeWarrior and always returns @false elsewhere. + always returns @false elsewhere. @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(); //@}