libcwd: The C++ Debugging Support Library - Reference Manual
Author: Carlo Wood
Description: C++ debugging support library with ostream debug output
Keywords: libcwd, debug output, debug facility, debug channel, object orientation, OO, C++, nested debug output, ostream, memory allocation, debugging, source file and line number

Main Page Reference Manual Namespace List Compound List Namespace Members Compound Members File Members

# libcwd/debug.h File Reference

This is the main header file of libcwd. More...

`#include <libcwd/libraries_debug.h>`
`#include <iostream>`

Go to the source code of this file.

## Defines
#define | DEBUGCHANNELS
| The namespace containing the current debug channels (dc) namespace.
#define | Debug(x)
| Encapsulation macro for general debugging code.
#define | Dout(cntrl, data)
| Macro for writing debug output.
#define | DoutFatal(cntrl, data)
| Macro for writing fatal debug output to the default debug object libcw_do .
#define | ForAllDebugChannels(STATEMENT...)
| Looping over all debug channels.
#define | ForAllDebugObjects(STATEMENT...)
| Looping over all debug objects.

## Detailed Description

This is the main header file of libcwd.

Don't include this header file directly. Instead use a custom debug.h header file that includes this file, that will allow others to compile your application without having libcwd installed.

## Define Documentation

#define Debug | ( | x |  | ) |

Encapsulation macro for general debugging code.

The parameter of this macro can be arbitrary code that will be eliminated from the application when the macro CWDEBUG is not defined.

It uses the namespaces DEBUGCHANNELS and libcwd, making it unnecessary to use the the full scopes for debug channels and utility functions provided by libcwd.

Examples:

     Debug( check_configuration() );                        // Configuration consistency check.
     Debug( dc::notice.on() );                              // Switch debug channel NOTICE on.
     Debug( libcw_do.on() );                                // Turn all debugging temporally off.
     Debug( list_channels_on(libcw_do) );                   // List all debug channels.
     Debug( make_all_allocations_invisible_except(NULL) );  // Hide all allocations so far.
     Debug( list_allocations_on(libcw_do) );                // List all allocations.
     Debug( libcw_do.set_ostream(&std::cout) );             // Use std::cout as debug output stream.
     Debug( libcw_do.set_ostream(&std::cout, &mutex) );     // use `mutex' as lock for std::cout.
     Debug( libcw_do.inc_indent(4) );                       // Increment indentation by 4 spaces.
     Debug( libcw_do.get_ostream()->flush() );              // Flush the current debug output stream.

#define DEBUGCHANNELS

The namespace containing the current debug channels (dc) namespace.

This macro is internally used by libcwd macros to include the chosen set of debug channels. For details please read section The Custom debug.h File.

#define Dout | ( | cntrl,
|  | data |  | ) |

Macro for writing debug output.

This macro is used for writing debug output to the default debug object libcw_do . No code is generated when the macro CWDEBUG is not defined, in that case the macro Dout is replaced by white space.

The macro Dout uses libcwds debug object libcw_do . You will have to define your own macro when you want to use a second debug object. Read chapter Design Consideration Concerning Macros for an explanation of why a macro was used instead of an inline function.

See also:
  Control Flags
  Predefined Debug Channels
  Defining your own debug channels
  Defining your own debug objects
  Nested debug calls

Examples:

     Dout(dc::notice, "Hello World");
     Dout(dc::malloc|dc::warning, "Out of memory in function " << func_name);
     Dout(dc::notice|blank_label_cf, "The content of the object is: " << std::hex << obj);

Referenced by libcwd::debug_ct::set_ostream().