X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/9f1ce8bfa92ee31fcb7633f3e59564bac17ff5e8..ca282726be518ce2f214b890dbaafce736f14e36:/interface/wx/debug.h diff --git a/interface/wx/debug.h b/interface/wx/debug.h index d0e98d385e..7e787e88c4 100644 --- a/interface/wx/debug.h +++ b/interface/wx/debug.h @@ -1,14 +1,70 @@ ///////////////////////////////////////////////////////////////////////////// -// 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. @@ -25,6 +81,32 @@ */ #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. @@ -163,6 +245,37 @@ */ #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 + 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 @@ -187,7 +300,7 @@ 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. @@ -204,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(); //@}