497 lines
20 KiB
C++
497 lines
20 KiB
C++
/////////////////////////////////////////////////////////////////////////////
|
|
// Name: wx/debug.h
|
|
// Purpose: Misc debug functions and macros
|
|
// Author: Vadim Zeitlin
|
|
// Created: 29/01/98
|
|
// Copyright: (c) 1998-2009 Vadim Zeitlin <vadim@wxwidgets.org>
|
|
// Licence: wxWindows licence
|
|
/////////////////////////////////////////////////////////////////////////////
|
|
|
|
#ifndef _WX_DEBUG_H_
|
|
#define _WX_DEBUG_H_
|
|
|
|
#if !defined(__WXWINCE__)
|
|
#include <assert.h>
|
|
#endif // systems without assert.h
|
|
|
|
#include <limits.h> // for CHAR_BIT used below
|
|
|
|
#include "wx/chartype.h" // for __TFILE__ and wxChar
|
|
#include "wx/cpp.h" // for __WXFUNCTION__
|
|
#include "wx/dlimpexp.h" // for WXDLLIMPEXP_FWD_BASE
|
|
|
|
class WXDLLIMPEXP_FWD_BASE wxString;
|
|
class WXDLLIMPEXP_FWD_BASE wxCStrData;
|
|
|
|
// ----------------------------------------------------------------------------
|
|
// Defines controlling the debugging macros
|
|
// ----------------------------------------------------------------------------
|
|
|
|
/*
|
|
wxWidgets can be built with several different levels of debug support
|
|
specified by the value of wxDEBUG_LEVEL constant:
|
|
|
|
0: No assertion macros at all, this should only be used when optimizing
|
|
for resource-constrained systems (typically embedded ones).
|
|
1: Default level, most of the assertions are enabled.
|
|
2: Maximal (at least for now): asserts which are "expensive"
|
|
(performance-wise) or only make sense for finding errors in wxWidgets
|
|
itself, as opposed to bugs in applications using it, are also enabled.
|
|
*/
|
|
|
|
// unless wxDEBUG_LEVEL is predefined (by configure or via wx/setup.h under
|
|
// Windows), use the default
|
|
#if !defined(wxDEBUG_LEVEL)
|
|
#define wxDEBUG_LEVEL 1
|
|
#endif // !defined(wxDEBUG_LEVEL)
|
|
|
|
/*
|
|
__WXDEBUG__ is defined when wxDEBUG_LEVEL != 0. This is done mostly for
|
|
compatibility but it also provides a simpler way to check if asserts and
|
|
debug logging is enabled at all.
|
|
*/
|
|
#if wxDEBUG_LEVEL > 0
|
|
#ifndef __WXDEBUG__
|
|
#define __WXDEBUG__
|
|
#endif
|
|
#else
|
|
#undef __WXDEBUG__
|
|
#endif
|
|
|
|
// Finally there is also a very old WXDEBUG macro not used anywhere at all, it
|
|
// is only defined for compatibility.
|
|
#ifdef __WXDEBUG__
|
|
#if !defined(WXDEBUG) || !WXDEBUG
|
|
#undef WXDEBUG
|
|
#define WXDEBUG 1
|
|
#endif // !WXDEBUG
|
|
#endif // __WXDEBUG__
|
|
|
|
// ----------------------------------------------------------------------------
|
|
// Handling assertion failures
|
|
// ----------------------------------------------------------------------------
|
|
|
|
/*
|
|
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);
|
|
|
|
#if wxDEBUG_LEVEL
|
|
|
|
// the global assert handler function, if it is NULL asserts don't check their
|
|
// conditions
|
|
extern WXDLLIMPEXP_DATA_BASE(wxAssertHandler_t) wxTheAssertHandler;
|
|
|
|
/*
|
|
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 or 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.
|
|
*/
|
|
inline wxAssertHandler_t wxSetAssertHandler(wxAssertHandler_t handler)
|
|
{
|
|
const wxAssertHandler_t old = wxTheAssertHandler;
|
|
wxTheAssertHandler = handler;
|
|
return old;
|
|
}
|
|
|
|
/*
|
|
Reset the default assert handler.
|
|
|
|
This may be used to enable asserts, which are disabled by default in this
|
|
case, for programs built in release build (NDEBUG defined).
|
|
*/
|
|
extern void WXDLLIMPEXP_BASE wxSetDefaultAssertHandler();
|
|
|
|
#else // !wxDEBUG_LEVEL
|
|
|
|
// provide empty stubs in case assertions are completely disabled
|
|
//
|
|
// NB: can't use WXUNUSED() here as we're included from wx/defs.h before it is
|
|
// defined
|
|
inline wxAssertHandler_t wxSetAssertHandler(wxAssertHandler_t /* handler */)
|
|
{
|
|
return NULL;
|
|
}
|
|
|
|
inline void wxSetDefaultAssertHandler() { }
|
|
|
|
#endif // wxDEBUG_LEVEL/!wxDEBUG_LEVEL
|
|
|
|
// simply a synonym for wxSetAssertHandler(NULL)
|
|
inline void wxDisableAsserts() { wxSetAssertHandler(NULL); }
|
|
|
|
/*
|
|
A macro which disables asserts for applications compiled in release build.
|
|
|
|
By default, wxIMPLEMENT_APP (or rather wxIMPLEMENT_WXWIN_MAIN) disable the
|
|
asserts in the applications compiled in the release build by calling this.
|
|
It does nothing if NDEBUG is not defined.
|
|
*/
|
|
#ifdef NDEBUG
|
|
#define wxDISABLE_ASSERTS_IN_RELEASE_BUILD() wxDisableAsserts()
|
|
#else
|
|
#define wxDISABLE_ASSERTS_IN_RELEASE_BUILD()
|
|
#endif
|
|
|
|
#if wxDEBUG_LEVEL
|
|
|
|
/*
|
|
wxOnAssert() is used by the debugging macros defined below. Different
|
|
overloads are needed because these macros can be used with or without wxT().
|
|
|
|
All of them are implemented in src/common/appcmn.cpp and unconditionally
|
|
call wxTheAssertHandler so the caller must check that it is non-NULL
|
|
(assert macros do it).
|
|
*/
|
|
|
|
#if wxUSE_UNICODE
|
|
|
|
// these overloads are the ones typically used by debugging macros: we have to
|
|
// provide wxChar* msg version because it's common to use wxT() in the macros
|
|
// and finally, we can't use const wx(char)* msg = NULL, because that would
|
|
// be ambiguous
|
|
//
|
|
// also notice that these functions can't be inline as wxString is not defined
|
|
// yet (and can't be as wxString code itself may use assertions)
|
|
extern WXDLLIMPEXP_BASE void wxOnAssert(const char *file,
|
|
int line,
|
|
const char *func,
|
|
const char *cond);
|
|
|
|
extern WXDLLIMPEXP_BASE void wxOnAssert(const char *file,
|
|
int line,
|
|
const char *func,
|
|
const char *cond,
|
|
const char *msg);
|
|
|
|
extern WXDLLIMPEXP_BASE void wxOnAssert(const char *file,
|
|
int line,
|
|
const char *func,
|
|
const char *cond,
|
|
const wxChar *msg) ;
|
|
#endif /* wxUSE_UNICODE */
|
|
|
|
// this version is for compatibility with wx 2.8 Unicode build only, we don't
|
|
// use it ourselves any more except in ANSI-only build in which case it is all
|
|
// we need
|
|
extern WXDLLIMPEXP_BASE void wxOnAssert(const wxChar *file,
|
|
int line,
|
|
const char *func,
|
|
const wxChar *cond,
|
|
const wxChar *msg = NULL);
|
|
|
|
// these overloads work when msg passed to debug macro is a string and we
|
|
// also have to provide wxCStrData overload to resolve ambiguity which would
|
|
// otherwise arise from wxASSERT( s.c_str() )
|
|
extern WXDLLIMPEXP_BASE void wxOnAssert(const wxString& file,
|
|
int line,
|
|
const wxString& func,
|
|
const wxString& cond,
|
|
const wxString& msg);
|
|
|
|
extern WXDLLIMPEXP_BASE void wxOnAssert(const wxString& file,
|
|
int line,
|
|
const wxString& func,
|
|
const wxString& cond);
|
|
|
|
extern WXDLLIMPEXP_BASE void wxOnAssert(const char *file,
|
|
int line,
|
|
const char *func,
|
|
const char *cond,
|
|
const wxCStrData& msg);
|
|
|
|
extern WXDLLIMPEXP_BASE void wxOnAssert(const char *file,
|
|
int line,
|
|
const char *func,
|
|
const char *cond,
|
|
const wxString& msg);
|
|
|
|
#endif // wxDEBUG_LEVEL
|
|
|
|
|
|
// ----------------------------------------------------------------------------
|
|
// Debugging macros
|
|
// ----------------------------------------------------------------------------
|
|
|
|
/*
|
|
Assertion macros: check if the condition is true and call assert handler
|
|
(which will by default notify the user about failure) if it isn't.
|
|
|
|
wxASSERT and wxFAIL macros as well as wxTrap() function do nothing at all
|
|
if wxDEBUG_LEVEL is 0 however they do check their conditions at default
|
|
debug level 1, unlike the previous wxWidgets versions.
|
|
|
|
wxASSERT_LEVEL_2 is meant to be used for "expensive" asserts which should
|
|
normally be disabled because they have a big impact on performance and so
|
|
this macro only does anything if wxDEBUG_LEVEL >= 2.
|
|
*/
|
|
#if wxDEBUG_LEVEL
|
|
// wxTrap() can be used to break into the debugger unconditionally
|
|
// (assuming the program is running under debugger, of course).
|
|
//
|
|
// If possible, we prefer to define it as a macro rather than as a function
|
|
// to open the debugger at the position where we trapped and not inside the
|
|
// trap function itself which is not very useful.
|
|
#if wxCHECK_VISUALC_VERSION(7)
|
|
#define wxTrap() __debugbreak()
|
|
#else
|
|
extern WXDLLIMPEXP_BASE void wxTrap();
|
|
#endif // Win VisualC
|
|
|
|
// Global flag used to indicate that assert macros should call wxTrap(): it
|
|
// is set by the default assert handler if the user answers yes to the
|
|
// question of whether to trap.
|
|
extern WXDLLIMPEXP_DATA_BASE(bool) wxTrapInAssert;
|
|
|
|
// This macro checks if the condition is true and calls the assert handler
|
|
// with the provided message if it isn't and finally traps if the special
|
|
// flag indicating that it should do it was set by the handler.
|
|
//
|
|
// Notice that we don't use the handler return value for compatibility
|
|
// reasons (if we changed its return type, we'd need to change wxApp::
|
|
// OnAssertFailure() too which would break user code overriding it), hence
|
|
// the need for the ugly global flag.
|
|
#define wxASSERT_MSG(cond, msg) \
|
|
wxSTATEMENT_MACRO_BEGIN \
|
|
if ( wxTheAssertHandler && !(cond) && \
|
|
(wxOnAssert(__FILE__, __LINE__, __WXFUNCTION__, \
|
|
#cond, msg), wxTrapInAssert) ) \
|
|
{ \
|
|
wxTrapInAssert = false; \
|
|
wxTrap(); \
|
|
} \
|
|
wxSTATEMENT_MACRO_END
|
|
|
|
// a version without any additional message, don't use unless condition
|
|
// itself is fully self-explanatory
|
|
#define wxASSERT(cond) wxASSERT_MSG(cond, (const char*)NULL)
|
|
|
|
// wxFAIL is a special form of assert: it always triggers (and so is
|
|
// usually used in normally unreachable code)
|
|
#define wxFAIL_COND_MSG(cond, msg) \
|
|
wxSTATEMENT_MACRO_BEGIN \
|
|
if ( wxTheAssertHandler && \
|
|
(wxOnAssert(__FILE__, __LINE__, __WXFUNCTION__, \
|
|
cond, msg), wxTrapInAssert) ) \
|
|
{ \
|
|
wxTrapInAssert = false; \
|
|
wxTrap(); \
|
|
} \
|
|
wxSTATEMENT_MACRO_END
|
|
|
|
#define wxFAIL_MSG(msg) wxFAIL_COND_MSG("Assert failure", msg)
|
|
#define wxFAIL wxFAIL_MSG((const char*)NULL)
|
|
#else // !wxDEBUG_LEVEL
|
|
#define wxTrap()
|
|
|
|
#define wxASSERT(cond)
|
|
#define wxASSERT_MSG(cond, msg)
|
|
#define wxFAIL
|
|
#define wxFAIL_MSG(msg)
|
|
#define wxFAIL_COND_MSG(cond, msg)
|
|
#endif // wxDEBUG_LEVEL
|
|
|
|
#if wxDEBUG_LEVEL >= 2
|
|
#define wxASSERT_LEVEL_2_MSG(cond, msg) wxASSERT_MSG(cond, msg)
|
|
#define wxASSERT_LEVEL_2(cond) wxASSERT(cond)
|
|
#else // wxDEBUG_LEVEL < 2
|
|
#define wxASSERT_LEVEL_2_MSG(cond, msg)
|
|
#define wxASSERT_LEVEL_2(cond)
|
|
#endif
|
|
|
|
// This is simply a wrapper for the standard abort() which is not available
|
|
// under all platforms.
|
|
//
|
|
// It isn't really debug-related but there doesn't seem to be any better place
|
|
// for it, so declare it here and define it in appbase.cpp, together with
|
|
// wxTrap().
|
|
extern void WXDLLIMPEXP_BASE wxAbort();
|
|
|
|
/*
|
|
wxCHECK macros always check their conditions, setting debug level to 0 only
|
|
makes them silent in case of failure, otherwise -- including at default
|
|
debug level 1 -- they call the assert handler if the condition is false
|
|
|
|
They are supposed to be used only in invalid situation: for example, an
|
|
invalid parameter (e.g. a NULL pointer) is passed to a function. Instead of
|
|
dereferencing it and causing core dump the function might use
|
|
|
|
wxCHECK_RET( p != NULL, "pointer can't be NULL" )
|
|
*/
|
|
|
|
// the generic macro: takes the condition to check, the statement to be executed
|
|
// in case the condition is false and the message to pass to the assert handler
|
|
#define wxCHECK2_MSG(cond, op, msg) \
|
|
if ( cond ) \
|
|
{} \
|
|
else \
|
|
{ \
|
|
wxFAIL_COND_MSG(#cond, msg); \
|
|
op; \
|
|
} \
|
|
struct wxDummyCheckStruct /* just to force a semicolon */
|
|
|
|
// check which returns with the specified return code if the condition fails
|
|
#define wxCHECK_MSG(cond, rc, msg) wxCHECK2_MSG(cond, return rc, msg)
|
|
|
|
// check that expression is true, "return" if not (also FAILs in debug mode)
|
|
#define wxCHECK(cond, rc) wxCHECK_MSG(cond, rc, (const char*)NULL)
|
|
|
|
// check that expression is true, perform op if not
|
|
#define wxCHECK2(cond, op) wxCHECK2_MSG(cond, op, (const char*)NULL)
|
|
|
|
// special form of wxCHECK2: as wxCHECK, but for use in void functions
|
|
//
|
|
// NB: there is only one form (with msg parameter) and it's intentional:
|
|
// there is no other way to tell the caller what exactly went wrong
|
|
// from the void function (of course, the function shouldn't be void
|
|
// to begin with...)
|
|
#define wxCHECK_RET(cond, msg) wxCHECK2_MSG(cond, return, msg)
|
|
|
|
|
|
// ----------------------------------------------------------------------------
|
|
// Compile time asserts
|
|
//
|
|
// Unlike the normal assert and related macros above which are checked during
|
|
// the program run-time the macros below will result in a compilation error if
|
|
// the condition they check is false. This is usually used to check the
|
|
// expressions containing sizeof()s which cannot be tested with the
|
|
// preprocessor. If you can use the #if's, do use them as you can give a more
|
|
// detailed error message then.
|
|
// ----------------------------------------------------------------------------
|
|
|
|
/*
|
|
How this works (you don't have to understand it to be able to use the
|
|
macros): we rely on the fact that it is invalid to define a named bit field
|
|
in a struct of width 0. All the rest are just the hacks to minimize the
|
|
possibility of the compiler warnings when compiling this macro: in
|
|
particular, this is why we define a struct and not an object (which would
|
|
result in a warning about unused variable) and a named struct (otherwise we'd
|
|
get a warning about an unnamed struct not used to define an object!).
|
|
*/
|
|
|
|
#define wxMAKE_UNIQUE_ASSERT_NAME wxMAKE_UNIQUE_NAME(wxAssert_)
|
|
|
|
/*
|
|
The second argument of this macro must be a valid C++ identifier and not a
|
|
string. I.e. you should use it like this:
|
|
|
|
wxCOMPILE_TIME_ASSERT( sizeof(int) >= 2, YourIntsAreTooSmall );
|
|
|
|
It may be used both within a function and in the global scope.
|
|
*/
|
|
#if defined(__WATCOMC__)
|
|
/* avoid "unused symbol" warning */
|
|
#define wxCOMPILE_TIME_ASSERT(expr, msg) \
|
|
class wxMAKE_UNIQUE_ASSERT_NAME { \
|
|
unsigned int msg: expr; \
|
|
wxMAKE_UNIQUE_ASSERT_NAME() { wxUnusedVar(msg); } \
|
|
}
|
|
#elif defined( __VMS )
|
|
namespace wxdebug{
|
|
|
|
// HP aCC cannot deal with missing names for template value parameters
|
|
template <bool x> struct STATIC_ASSERTION_FAILURE;
|
|
|
|
template <> struct STATIC_ASSERTION_FAILURE<true> { enum { value = 1 }; };
|
|
|
|
// HP aCC cannot deal with missing names for template value parameters
|
|
template<int x> struct static_assert_test{};
|
|
|
|
}
|
|
#define WX_JOIN( X, Y ) X##Y
|
|
#define WX_STATIC_ASSERT_BOOL_CAST(x) (bool)(x)
|
|
#define wxCOMPILE_TIME_ASSERT(expr, msg) \
|
|
typedef ::wxdebug::static_assert_test<\
|
|
sizeof(::wxdebug::STATIC_ASSERTION_FAILURE< WX_STATIC_ASSERT_BOOL_CAST( expr ) >)>\
|
|
WX_JOIN(wx_static_assert_typedef_, __LINE__)
|
|
#else
|
|
#define wxCOMPILE_TIME_ASSERT(expr, msg) \
|
|
struct wxMAKE_UNIQUE_ASSERT_NAME { unsigned int msg: expr; }
|
|
#endif
|
|
|
|
/*
|
|
When using VC++ 6 with "Edit and Continue" on, the compiler completely
|
|
mishandles __LINE__ and so wxCOMPILE_TIME_ASSERT() doesn't work, provide a
|
|
way to make "unique" assert names by specifying a unique prefix explicitly
|
|
*/
|
|
#define wxMAKE_UNIQUE_ASSERT_NAME2(text) wxCONCAT(wxAssert_, text)
|
|
|
|
#define wxCOMPILE_TIME_ASSERT2(expr, msg, text) \
|
|
struct wxMAKE_UNIQUE_ASSERT_NAME2(text) { unsigned int msg: expr; }
|
|
|
|
// helpers for wxCOMPILE_TIME_ASSERT below, for private use only
|
|
#define wxMAKE_BITSIZE_MSG(type, size) type ## SmallerThan ## size ## Bits
|
|
|
|
// a special case of compile time assert: check that the size of the given type
|
|
// is at least the given number of bits
|
|
#define wxASSERT_MIN_BITSIZE(type, size) \
|
|
wxCOMPILE_TIME_ASSERT(sizeof(type) * CHAR_BIT >= size, \
|
|
wxMAKE_BITSIZE_MSG(type, size))
|
|
|
|
|
|
// ----------------------------------------------------------------------------
|
|
// other miscellaneous debugger-related functions
|
|
// ----------------------------------------------------------------------------
|
|
|
|
/*
|
|
Return true if we're running under debugger.
|
|
|
|
Currently only really works under Win32 and just returns false elsewhere.
|
|
*/
|
|
#if defined(__WIN32__)
|
|
extern bool WXDLLIMPEXP_BASE wxIsDebuggerRunning();
|
|
#else // !Mac
|
|
inline bool wxIsDebuggerRunning() { return false; }
|
|
#endif // Mac/!Mac
|
|
|
|
// An assert helper used to avoid warning when testing constant expressions,
|
|
// i.e. wxASSERT( sizeof(int) == 4 ) can generate a compiler warning about
|
|
// expression being always true, but not using
|
|
// wxASSERT( wxAssertIsEqual(sizeof(int), 4) )
|
|
//
|
|
// NB: this is made obsolete by wxCOMPILE_TIME_ASSERT() and should no
|
|
// longer be used.
|
|
extern bool WXDLLIMPEXP_BASE wxAssertIsEqual(int x, int y);
|
|
|
|
// Use of wxFalse instead of false suppresses compiler warnings about testing
|
|
// constant expression
|
|
extern WXDLLIMPEXP_DATA_BASE(const bool) wxFalse;
|
|
|
|
#define wxAssertFailure wxFalse
|
|
|
|
// This is similar to WXUNUSED() and useful for parameters which are only used
|
|
// in assertions.
|
|
#if wxDEBUG_LEVEL
|
|
#define WXUNUSED_UNLESS_DEBUG(param) param
|
|
#else
|
|
#define WXUNUSED_UNLESS_DEBUG(param) WXUNUSED(param)
|
|
#endif
|
|
|
|
|
|
#endif // _WX_DEBUG_H_
|