git.saurik.com Git - wxWidgets.git/blame_incremental

... / ...

Commit	Line	Data
	1	/**
	2	* Name: wx/debug.h
	3	* Purpose: Misc debug functions and macros
	4	* Author: Vadim Zeitlin
	5	* Modified by: Ryan Norton (Converted to C)
	6	* Created: 29/01/98
	7	* RCS-ID: $Id$
	8	* Copyright: (c) 1998 Vadim Zeitlin <zeitlin@dptmaths.ens-cachan.fr>
	9	* Licence: wxWindows licence
	10	*/
	11
	12	/* THIS IS A C FILE, DON'T USE C++ FEATURES (IN PARTICULAR COMMENTS) IN IT */
	13
	14	#ifndef _WX_DEBUG_H_
	15	#define _WX_DEBUG_H_
	16
	17	#ifndef __WXWINCE__
	18	#include <assert.h>
	19	#endif
	20	#include <limits.h> /* for CHAR_BIT used below */
	21
	22	#include "wx/chartype.h" /* for __TFILE__ and wxChar */
	23
	24	/* ---------------------------------------------------------------------------- */
	25	/* Defines controlling the debugging macros */
	26	/* ---------------------------------------------------------------------------- */
	27
	28	/* if _DEBUG is defined (MS VC++ and others use it in debug builds), define */
	29	/* __WXDEBUG__ too */
	30	#ifdef _DEBUG
	31	#ifndef __WXDEBUG__
	32	#define __WXDEBUG__
	33	#endif /* !__WXDEBUG__ */
	34	#endif /* _DEBUG */
	35
	36	/* if NDEBUG is defined (<assert.h> uses it), undef __WXDEBUG__ and WXDEBUG */
	37	#ifdef NDEBUG
	38	#undef __WXDEBUG__
	39	#undef WXDEBUG
	40	#endif /* NDEBUG */
	41
	42	/* if __WXDEBUG__ is defined, make sure that WXDEBUG is defined and >= 1 */
	43	#ifdef __WXDEBUG__
	44	#if !defined(WXDEBUG) \|\| !WXDEBUG
	45	#undef WXDEBUG
	46	#define WXDEBUG 1
	47	#endif /* !WXDEBUG */
	48	#endif /* __WXDEBUG__ */
	49
	50	#ifndef __WXFUNCTION__
	51	/* TODO: add more compilers supporting __FUNCTION__ */
	52	#if defined(__DMC__)
	53	/*
	54	__FUNCTION__ happens to be not defined within class members
	55	http://www.digitalmars.com/drn-bin/wwwnews?c%2B%2B.beta/485
	56	*/
	57	#define __WXFUNCTION__ (NULL)
	58	#elif defined(__GNUC__) \|\| \
	59	(defined(_MSC_VER) && _MSC_VER >= 1300) \|\| \
	60	defined(__FUNCTION__)
	61	#define __WXFUNCTION__ __FUNCTION__
	62	#else
	63	/* still define __WXFUNCTION__ to avoid #ifdefs elsewhere */
	64	#define __WXFUNCTION__ (NULL)
	65	#endif
	66	#endif /* __WXFUNCTION__ already defined */
	67
	68	/* ---------------------------------------------------------------------------- */
	69	/* Debugging macros */
	70	/* */
	71	/* All debugging macros rely on ASSERT() which in turn calls the user-defined */
	72	/* OnAssert() function. To keep things simple, it's called even when the */
	73	/* expression is true (i.e. everything is ok) and by default does nothing: just */
	74	/* returns the same value back. But if you redefine it to do something more sexy */
	75	/* (popping up a message box in your favourite GUI, sending you e-mail or */
	76	/* whatever) it will affect all ASSERTs, FAILs and CHECKs in your code. */
	77	/* */
	78	/* Warning: if you don't like advice on programming style, don't read */
	79	/* further! ;-) */
	80	/* */
	81	/* Extensive use of these macros is recommended! Remember that ASSERTs are */
	82	/* disabled in final build (without __WXDEBUG__ defined), so they add strictly */
	83	/* nothing to your program's code. On the other hand, CHECK macros do stay */
	84	/* even in release builds, but in general are not much of a burden, while */
	85	/* a judicious use of them might increase your program's stability. */
	86	/* ---------------------------------------------------------------------------- */
	87
	88	/* Macros which are completely disabled in 'release' mode */
	89	/* */
	90	/* NB: these functions are implemented in src/common/appcmn.cpp */
	91	#if defined(__cplusplus) && defined(__WXDEBUG__)
	92	/*
	93	This function is called whenever one of debugging macros fails (i.e.
	94	condition is false in an assertion). To customize its behaviour, override
	95	wxApp::OnAssertFailure().
	96
	97	Parameters:
	98	szFile and nLine - file name and line number of the ASSERT
	99	szFunc - function name of the ASSERT, may be NULL (NB: ASCII)
	100	szCond - text form of the condition which failed
	101	szMsg - optional message explaining the reason
	102	*/
	103
	104	/* this version is for compatibility with wx 2.8 Unicode build only: */
	105	extern void WXDLLIMPEXP_BASE wxOnAssert(const wxChar *szFile,
	106	int nLine,
	107	const char *szFunc,
	108	const wxChar *szCond,
	109	const wxChar *szMsg = NULL);
	110
	111	#if wxUSE_UNICODE
	112	/* char versions are used by debugging macros; we have to provide
	113	wxChar* szMsg version because it's common to use _T() in the macros
	114	and finally, we can't use const wx(char)* szMsg = NULL, because that
	115	would be ambiguous: */
	116	extern void WXDLLIMPEXP_BASE wxOnAssert(const char *szFile,
	117	int nLine,
	118	const char *szFunc,
	119	const char *szCond);
	120
	121	extern void WXDLLIMPEXP_BASE wxOnAssert(const char *szFile,
	122	int nLine,
	123	const char *szFunc,
	124	const char *szCond,
	125	const char *szMsg);
	126
	127	extern void WXDLLIMPEXP_BASE wxOnAssert(const char *szFile,
	128	int nLine,
	129	const char *szFunc,
	130	const char *szCond,
	131	const wxChar *szMsg);
	132	#endif /* wxUSE_UNICODE */
	133
	134	class WXDLLIMPEXP_FWD_BASE wxString;
	135	class WXDLLIMPEXP_FWD_BASE wxCStrData;
	136
	137	/* these two work when szMsg passed to debug macro is a string,
	138	we also have to provide wxCStrData overload to resolve ambiguity
	139	which would otherwise arise from wxASSERT( s.c_str() ): */
	140	extern void WXDLLIMPEXP_BASE wxOnAssert(const wxString& szFile,
	141	int nLine,
	142	const wxString& szFunc,
	143	const wxString& szCond,
	144	const wxString& szMsg);
	145
	146	extern void WXDLLIMPEXP_BASE wxOnAssert(const wxString& szFile,
	147	int nLine,
	148	const wxString& szFunc,
	149	const wxString& szCond);
	150
	151	extern void WXDLLIMPEXP_BASE wxOnAssert(const char *szFile,
	152	int nLine,
	153	const char *szFunc,
	154	const char *szCond,
	155	const wxCStrData& msg);
	156
	157	extern void WXDLLIMPEXP_BASE wxOnAssert(const char *szFile,
	158	int nLine,
	159	const char *szFunc,
	160	const char *szCond,
	161	const wxString& szMsg);
	162
	163	/* call this function to break into the debugger unconditionally (assuming */
	164	/* the program is running under debugger, of course) */
	165	extern void WXDLLIMPEXP_BASE wxTrap();
	166
	167	/* generic assert macro */
	168	#define wxASSERT(cond) wxASSERT_MSG(cond, (const char*)NULL)
	169
	170
	171	/* assert with additional message explaining its cause */
	172
	173	/* compilers can give a warning (such as "possible unwanted ;") when using */
	174	/* the default definition of wxASSERT_MSG so we provide an alternative */
	175	#if defined(__MWERKS__)
	176	#define wxASSERT_MSG(cond, msg) \
	177	if ( cond ) \
	178	{} \
	179	else \
	180	wxOnAssert(__FILE__, __LINE__, __WXFUNCTION__, #cond, msg)
	181	#else
	182	#define wxASSERT_MSG(cond, msg) \
	183	if ( cond ) \
	184	; \
	185	else \
	186	wxOnAssert(__FILE__, __LINE__, __WXFUNCTION__, #cond, msg)
	187	#endif
	188
	189	/* special form of assert: always triggers it (in debug mode) */
	190	#define wxFAIL wxFAIL_MSG((const char*)NULL)
	191
	192	/* FAIL with some message */
	193	#define wxFAIL_MSG(msg) wxFAIL_COND_MSG("wxAssertFailure", msg)
	194
	195	/* FAIL with some message and a condition */
	196	#define wxFAIL_COND_MSG(cond, msg) \
	197	wxOnAssert(__FILE__, __LINE__, __WXFUNCTION__, cond, msg)
	198
	199	/* An assert helper used to avoid warning when testing constant expressions, */
	200	/* i.e. wxASSERT( sizeof(int) == 4 ) can generate a compiler warning about */
	201	/* expression being always true, but not using */
	202	/* wxASSERT( wxAssertIsEqual(sizeof(int), 4) ) */
	203	/* */
	204	/* NB: this is made obsolete by wxCOMPILE_TIME_ASSERT() and should no */
	205	/* longer be used. */
	206	extern bool WXDLLIMPEXP_BASE wxAssertIsEqual(int x, int y);
	207	#else
	208	#define wxTrap()
	209
	210	/* nothing to do in release mode (hopefully at this moment there are */
	211	/* no more bugs ;-) */
	212	#define wxASSERT(cond)
	213	#define wxASSERT_MSG(cond, msg)
	214	#define wxFAIL
	215	#define wxFAIL_MSG(msg)
	216	#define wxFAIL_COND_MSG(cond, msg)
	217	#endif /* __WXDEBUG__ */
	218
	219	#ifdef __cplusplus
	220	/* Use of wxFalse instead of false suppresses compiler warnings about testing */
	221	/* constant expression */
	222	extern WXDLLIMPEXP_DATA_BASE(const bool) wxFalse;
	223	#endif
	224
	225	#define wxAssertFailure wxFalse
	226
	227	/* NB: the following macros also work in release mode! */
	228
	229	/*
	230	These macros must be used only in invalid situation: for example, an
	231	invalid parameter (e.g. a NULL pointer) is passed to a function. Instead of
	232	dereferencing it and causing core dump the function might try using
	233	CHECK( p != NULL ) or CHECK( p != NULL, return LogError("p is NULL!!") )
	234	*/
	235
	236	/* check that expression is true, "return" if not (also FAILs in debug mode) */
	237	#define wxCHECK(cond, rc) wxCHECK_MSG(cond, rc, (const char*)NULL)
	238
	239	/* as wxCHECK but with a message explaining why we fail */
	240	#define wxCHECK_MSG(cond, rc, msg) wxCHECK2_MSG(cond, return rc, msg)
	241
	242	/* check that expression is true, perform op if not */
	243	#define wxCHECK2(cond, op) wxCHECK2_MSG(cond, op, (const char*)NULL)
	244
	245	/* as wxCHECK2 but with a message explaining why we fail */
	246
	247	/* see comment near the definition of wxASSERT_MSG for the # if/else reason */
	248	#if defined(__MWERKS__)
	249	#define wxCHECK2_MSG(cond, op, msg) \
	250	if ( cond ) \
	251	{} \
	252	else \
	253	{ \
	254	wxFAIL_COND_MSG(#cond, msg); \
	255	op; \
	256	} \
	257	struct wxDummyCheckStruct /* just to force a semicolon */
	258	#else
	259	#define wxCHECK2_MSG(cond, op, msg) \
	260	if ( cond ) \
	261	; \
	262	else \
	263	{ \
	264	wxFAIL_COND_MSG(#cond, msg); \
	265	op; \
	266	} \
	267	struct wxDummyCheckStruct /* just to force a semicolon */
	268	#endif
	269
	270	/* special form of wxCHECK2: as wxCHECK, but for use in void functions */
	271	/* */
	272	/* NB: there is only one form (with msg parameter) and it's intentional: */
	273	/* there is no other way to tell the caller what exactly went wrong */
	274	/* from the void function (of course, the function shouldn't be void */
	275	/* to begin with...) */
	276	#define wxCHECK_RET(cond, msg) wxCHECK2_MSG(cond, return, msg)
	277
	278	/* ---------------------------------------------------------------------------- */
	279	/* Compile time asserts */
	280	/* */
	281	/* Unlike the normal assert and related macros above which are checked during */
	282	/* the program tun-time the macros below will result in a compilation error if */
	283	/* the condition they check is false. This is usually used to check the */
	284	/* expressions containing sizeof()s which cannot be tested with the */
	285	/* preprocessor. If you can use the #if's, do use them as you can give a more */
	286	/* detailed error message then. */
	287	/* ---------------------------------------------------------------------------- */
	288
	289	/*
	290	How this works (you don't have to understand it to be able to use the
	291	macros): we rely on the fact that it is invalid to define a named bit field
	292	in a struct of width 0. All the rest are just the hacks to minimize the
	293	possibility of the compiler warnings when compiling this macro: in
	294	particular, this is why we define a struct and not an object (which would
	295	result in a warning about unused variable) and a named struct (otherwise we'd
	296	get a warning about an unnamed struct not used to define an object!).
	297	*/
	298
	299	#define wxMAKE_UNIQUE_ASSERT_NAME wxMAKE_UNIQUE_NAME(wxAssert_)
	300
	301	/*
	302	The second argument of this macro must be a valid C++ identifier and not a
	303	string. I.e. you should use it like this:
	304
	305	wxCOMPILE_TIME_ASSERT( sizeof(int) >= 2, YourIntsAreTooSmall );
	306
	307	It may be used both within a function and in the global scope.
	308	*/
	309	#if defined(__WATCOMC__) && defined(__cplusplus)
	310	/* avoid "unused symbol" warning */
	311	#define wxCOMPILE_TIME_ASSERT(expr, msg) \
	312	class wxMAKE_UNIQUE_ASSERT_NAME { \
	313	unsigned int msg: expr; \
	314	wxMAKE_UNIQUE_ASSERT_NAME() { wxUnusedVar(msg); } \
	315	}
	316	#else
	317	#define wxCOMPILE_TIME_ASSERT(expr, msg) \
	318	struct wxMAKE_UNIQUE_ASSERT_NAME { unsigned int msg: expr; }
	319	#endif
	320
	321	/*
	322	When using VC++ 6 with "Edit and Continue" on, the compiler completely
	323	mishandles __LINE__ and so wxCOMPILE_TIME_ASSERT() doesn't work, provide a
	324	way to make "unique" assert names by specifying a unique prefix explicitly
	325	*/
	326	#define wxMAKE_UNIQUE_ASSERT_NAME2(text) wxCONCAT(wxAssert_, text)
	327
	328	#define wxCOMPILE_TIME_ASSERT2(expr, msg, text) \
	329	struct wxMAKE_UNIQUE_ASSERT_NAME2(text) { unsigned int msg: expr; }
	330
	331	/* helpers for wxCOMPILE_TIME_ASSERT below, for private use only */
	332	#define wxMAKE_BITSIZE_MSG(type, size) type ## SmallerThan ## size ## Bits
	333
	334	/* a special case of compile time assert: check that the size of the given type */
	335	/* is at least the given number of bits */
	336	#define wxASSERT_MIN_BITSIZE(type, size) \
	337	wxCOMPILE_TIME_ASSERT(sizeof(type) * CHAR_BIT >= size, \
	338	wxMAKE_BITSIZE_MSG(type, size))
	339
	340	/* ---------------------------------------------------------------------------- */
	341	/* other miscellaneous debugger-related functions */
	342	/* ---------------------------------------------------------------------------- */
	343
	344	/*
	345	Return true if we're running under debugger.
	346
	347	Currently this only really works under Win32 and Mac in CodeWarrior builds,
	348	it always returns false in other cases.
	349	*/
	350	#ifdef __cplusplus
	351	/* ABX: check __WIN32__ instead of __WXMSW__ for the same MSWBase in any Win32 port */
	352	#if defined(__WXMAC__) \|\| defined(__WIN32__)
	353	extern bool WXDLLIMPEXP_BASE wxIsDebuggerRunning();
	354	#else /* !Mac */
	355	inline bool wxIsDebuggerRunning() { return false; }
	356	#endif /* Mac/!Mac */
	357	#endif /* __cplusplus */
	358
	359	#endif /* _WX_DEBUG_H_ */