debug.h

Macros for printing debug messages.

o #define DEBUG_MAKE_INDENT
        (x)
Indents all messages in the current scope.
o #define DEBUG_SET_LEVEL
        (level)
Sets the current debugging level.
o #define DEBUG1_MSG
        (x)
Generates a level 1 message
o #define DEBUG2_MSG
        (x)
Generates a level 2 message
o #define DEBUG3_MSG
        (x)
Generates a level 3 message
o #define DEBUG4_MSG
        (x)
Generates a level 4 message
o #define DEBUG_MSG
        (x)
Generates a level 1 message.
o #define DEBUG_MSGF
        (x)
Generates a level 1 message without indentation.
o #define DEBUG_MSGN
        (x)
Generates a level 1 message terminated with a newline.
Files "debug.h" and "debug.cpp" implement means to print debug messages in a multithread safe way. Message are also marked with a thread identifier. Under Windows, debug messages are directly sent to the debugger using the Win32 function OutputDebugString. Under Unix, debug messages are printed on the controlling terminal, preferably using device /dev/tty.

The preprocessor variable DEBUGLVL defines which debug code is going to be compiled. Selecting -DDEBUGLVL=0 (the default) disables all debugging code. Selecting a positive values (e.g. -DDEBUGLVL=4) enables more and more debugging code.

Message output is controlled by the current debugging level (an integer between 0 and DEBUGLVL). Greater values enable more messages. The initial debugging level is set to the maximum value. The debugging level can be changed using macro DEBUG_SET_LEVEL.

Message indentation can be modified using macro DEBUG_MAKE_INDENT. Messages are generated by macro DEBUG_MSG or its variants. The argument of the macro can contain several components separated by operator <<, as demonstrated in the example below:

    DEBUG_MSG("The value of a[" << n << "] is " << a[n] << '\n');
    

One more preprocessor variable RUNTIME_DEBUG_ONLY enables compilation of debug code, but does not enable the debug messages automatically. In order to see them the program should use DEBUG_SET_LEVEL to change the level to anything greater than 0. Normally this happens when user specifies option -debug in the command line. Usage of RUNTIME_DEBUG_ONLY implies DEBUGLVL=1 if not specified otherwise.

Finally, -DNO_DEBUG can be used instead of -DDEBUGLVL=0.

Historical Comment --- Debug macros are rarely used in the reference DjVu library because Leon thinks that debugging messages unnecessarily clutter the code. Debug macros are used everywhere in the plugin code because Andrew thinks that code without debugging messages is close to useless. No agreement could be reached. Neither could they agree on if cluttering header files with huge documentation chunks helps to improve code readability.

Author:
Andrew Erofeev <eaf@geocities.com> -- initial implementation
Leon Bottou <leonb@research.att.com> -- cleanups
Version:
$Id: debug.h.html,v 1.12 2001/02/15 01:12:21 bcr Exp $

Alphabetic index Hierarchy of classes


DjVu is a trademark of LizardTech, Inc.
All other products mentioned are registered trademarks or trademarks of their respective companies.