/*
* _DEBUG.H
*
* Header file for ArchiveLib 1.0
*
* Copyright (c) 1994 Greenleaf Software, Inc.
* All Rights Reserved
*
* DESCRIPTION
*
* These macros and types are all used in the debug versions of the
* ArchiveLib.
*
* MACROS
*
* _ALAssertFailure()
* AL_ASSERT()
* AL_ASSERT_OBJECT()
* AL_CLASS_TAG()
*
* PROTOTYPES:
*
* IsBadWritePtr()
*
* ENUMERATED TYPES:
*
* _ALClassTags
*
* REVISION HISTORY
*
* May 26, 1994 1.0A : First release
*
*/
#ifndef __DEBUG_H
#define __DEBUG_H
/*
* _ALAssertFailure is the function called by AL_ASSERT() and
* AL_ASSERT_OBJECT() when their assertion fails.
*/
void AL_CFUNCTION _ALAssertFailure( const char AL_DLL_FAR *condition,
const char AL_DLL_FAR *filename,
int line,
const char AL_DLL_FAR *message,
... );
#ifdef NDEBUG
/*
* In the non-debug versions, both of these macros basically go away.
* The only difficulty is trying to avoid having the compilers generate
* error messages when they see this code. Maybe in NDEBUG mode I could
* change these to inline functions that do nothing?
*/
#define AL_ASSERT( condition, message ) ((void) 0)
#define AL_ASSERT_OBJECT( pointer, class, message ) ((void) 0)
#else
/*
* In debug mode, AL_ASSERT() tests the condition, and generates
* an abort with an error message when the condition fails.
*/
#define AL_ASSERT( condition, message ) \
( ( condition ) ? \
(void) 0 : \
_ALAssertFailure( #condition, \
__FILE__, \
__LINE__, \
message ) ) \
/*
* I can only call IsBadWritePtr() if TOOLHELP.DLL is available. As far
* as I know, it won't be available with any of the DOS Extenders
* The only way we have access to TOOLHELP.DLL is if we are *really*
* running under Windows, not some bogus imitation.
*/
#if !defined( AL_WINDOWS_GUI )
#define IsBadWritePtr( p, s ) 0
#endif
/*
* AL_ASSERT_OBJECT() is a great macro. It is used to test the
* validity of an object. This is a two step process. First,
* we make sure we are dealing with a good pointer. If not, an
* asserting error is triggered. This is much better than the
* GPF you would normally get from a bad pointer. Next, we
* test the GoodTag() macro, which verifies that this is
* a properly constructed object from the specified class. Of
* course, in NDEBUG mode this all goes away.
*
*/
#define AL_ASSERT_OBJECT( pointer, class, message ) \
( pointer == 0 || IsBadWritePtr( pointer, sizeof( class ) ) ) ? \
_ALAssertFailure( "IsBadWritePtr()", \
__FILE__, \
__LINE__, \
"%s: Bad pointer to object of class %s", \
message, \
#class ) \
: \
( ( (class *)pointer)->GoodTag() ? \
(void) 0 \
: \
_ALAssertFailure( #pointer "->GoodTag()", \
__FILE__, \
__LINE__, \
"%s: %s is not an object of class %s", \
message, \
#pointer, \
#class ) )
#endif
/*
* The AL_CLASS_TAG() macro assigns a new debug class and data
* member to each of the classes in ArchiveLib. Each of these
* debug classes uses a special integer tag (stored in the data member)
* to uniquely identify itself. These are the integer values of
* these integers.
*/
enum _ALClassTags {
_ALDeletedObjectTag = 0,
_ALStorageTag,
_ALFileTag,
_ALMemoryTag,
_ALEntryTag,
_ALEntryListTag,
_ALArchiveBaseTag,
_ALArchiveTag,
_ALMonitorTag,
_ALBarGraphTag,
_ALSpinnerTag,
_ALWindowsMessageTag,
_ALCompressionEngineTag,
_ALCopyEngineTag,
_ALGreenleafEngineTag,
_ALCompressedObjectTag,
_ALNameTag,
_ALWildCardExpanderTag,
};
/*
* AL_CLASS_TAG( x ) is a macro that is used to help debug
* ArchiveLib. The insertion of this macro in a class definition
* adds a new data member and member function to the class. The
* data member is an object of a class uniquely created by the
* macro. The reason the data member is a class object instead
* of a simple integer or character tag is this: By making it a
* class object, we can automatically assign it a valid value
* when constructed, and an invalid value when destroyed.
*
* The member function added to the class is called GoodTag().
* Once you have added AL_CLASS_TAG( x ) to your class definition,
* you can call object.GoodTag() anytime you want. It will return
* a true value only if the data member has the correct value,
*
* We make use of this function in AL_ASSERT_OBJECT(). It
* checks the value of this object frequently in member functions
* and destructors, generating an assertion failure if the object
* doesn't look like the correct type.
*
* Note that the ASSERT_OBJECT() statements generate no code when the
* library is compiled with NDEBUG, so this class will not be
* generating much low overhead. However, the data member will
* still be taking up a single byte in each instance.
*
* If you want to eliminate class tags, this line in will do it
* You will save one byte per instance. The best way to accomplish this
* is to define the macro in ALCUSTOM.H, then rebuild the library with
* macro AL_CUSTOM defined in your project. After you build this new
* version of the library, you must absolutely, positively, be sure
* that you continue to use AL_CUSTOM and ALCUSTOM.H when working
* with the library. If you don't, your library and your application
* will think that most classes in ArchiveLib are different sizes, and
* *nothing* will work.
*
*#define AL_CLASS_TAG( x ) int GoodTag(){ return 1; }
*/
#if defined( NDEBUG ) && !defined( AL_CLASS_TAG )
#define AL_CLASS_TAG( x ) class AL_CLASS_TYPE _ALTag##x { \
public : \
unsigned char mucTagVal; \
} mMyTag; \
int AL_PROTO GoodTag(){ return 1; }
#endif /* #if defined( NDEBUG ) && !defined( AL_CLASS_TAG ) */
#if !defined( NDEBUG ) && !defined( AL_CLASS_TAG )
#define AL_CLASS_TAG( x ) class AL_CLASS_TYPE _ALTag##x { \
public : \
AL_PROTO _ALTag##x(){ mucTagVal = x; } \
AL_PROTO ~_ALTag##x(){ mucTagVal = _ALDeletedObjectTag; } \
unsigned char mucTagVal; \
} mMyTag; \
int AL_PROTO GoodTag(){ return mMyTag.mucTagVal == x; }
#endif /* #if !defined( NDEBUG ) && !defined( AL_CLASS_TAG ) */
#endif /* #ifndef __DEBUG_H */