namespace dbg Debugging utilities. More... List of all Methods

Annotated List Files Globals Hierarchy Index

Public Types

• enum level { info, warning, error, fatal, tracing, debug, none, all }
• enum assertion_behaviour { assertions_abort, assertions_throw, assertions_continue }
• typedef const char * dbg_source
• typedef const unsigned int line_no_t
• typedef const char * func_name_t
• typedef const char * file_name_t
• struct source_pos
• typedef std::clock_t dbgclock_t
• typedef clock_t dbgclock_t
• struct dbg_exception
• struct assertion_exception
• struct sentinel_exception
• struct unimplemented_exception
• struct check_ptr_exception
• struct prefix
• struct indent
• struct assert_info
• class trace
• class post_mem_fun
• class post
• class compile_assertion
• class null_stream

Public Methods

• void  enable (level lvl, bool enabled)
• void  enable (level lvl, dbg_source src, bool enabled)
• void  enable_all (level lvl, bool enabled)
• std::ostream & out (level lvl, dbg_source src)
• inline std::ostream & out (level lvl)
• void  attach_ostream (level lvl, std::ostream &o)
• void  attach_ostream (level lvl, dbg_source src, std::ostream &o)
• void  detach_ostream (level lvl, std::ostream &o)
• void  detach_ostream (level lvl, dbg_source src, std::ostream &o)
• void  detach_all_ostreams (level lvl)
• void  detach_all_ostreams (level lvl, dbg_source src)
• inline std::ostream & info_out ()
• inline std::ostream & warning_out ()
• inline std::ostream & error_out ()
• inline std::ostream & fatal_out ()
• inline std::ostream & trace_out ()
• void  set_prefix (const char *prefix)
• void  enable_level_prefix (bool enabled)
• void  enable_time_prefix (bool enabled)
• std::ostream & operator<< (std::ostream &s, const prefix &p)
• std::ostream & operator<< (std::ostream &s, const indent &i)
• std::ostream & operator<< (std::ostream &s, const source_pos &pos)
• void  set_assertion_behaviour (level lvl, assertion_behaviour behaviour)
• void  set_assertion_period (dbgclock_t period)
• void  assertion (level lvl, dbg_source src, const assert_info &ai)
• inline void  assertion (level lvl, const assert_info &ai)
• inline void  assertion (dbg_source src, const assert_info &ai)
• inline void  assertion (const assert_info &ai)
• void  sentinel (level lvl, dbg_source src, const source_pos &here)
• inline void  sentinel (level lvl, const source_pos &here)
• inline void  sentinel (dbg_source src, const source_pos &here)
• inline void  sentinel (const source_pos &here)
• void  unimplemented (level lvl, dbg_source src, const source_pos &here)
• inline void  unimplemented (level lvl, const source_pos &here)
• inline void  unimplemented (dbg_source src, const source_pos &here)
• inline void  unimplemented (const source_pos &here)
• void  check_ptr (level lvl, dbg_source src, const void *p, const source_pos &here)
• inline void  check_ptr (level lvl, const void *p, const source_pos &here)
• inline void  check_ptr (dbg_source src, const void *p, const source_pos &here)
• inline void  check_ptr (const void *p, const source_pos &here)
• template inline unsigned int  array_size (T &array)
• void  check_bounds (level lvl, dbg_source src, int index, int bound, const source_pos &here)
• inline void  check_bounds (level lvl, dbg_source src, int index, int minbound, int maxbound, const source_pos &here)
• template void  check_bounds (level lvl, dbg_source src, int index, T &array, const source_pos &here)
• template void  check_bounds (level lvl, int index, T &array, const source_pos &here)
• template void  check_bounds (dbg_source src, int index, T &array, const source_pos &here)
• template void  check_bounds (int index, T &array, const source_pos &here)

Public Members

• const int version
• extern dbg_source default_source
• const dbg_source default_source

Detailed Description

The dbg namespace holds a number of C++ debugging utilities.

They allow you to include constraint checking in your code, and provide an integrated advanced stream-based logging facility.

The characteristics of this library are:

• Easy to use (not overly complex) (easy to write, easy to read, easy to use)
• Powerful
• Configurable
• No run time overhead when "compiled out"
• Minimises use of the preprocessor
• Can throw exceptions if required
• Can separate different "sources" of diagnostic output (these sources are differentiated by name)
• Designed to be a "standard" library (integrates with the style of the C++ standard library and works well with it)

Enabling debugging

To use dbg in your program you must #include <dbg.h> and compile with the DBG_ENABLED flag set.

If you build without DBG_ENABLED you will have no debugging support (neither constraints nor logging). There is no overhead building a program using these utilities when DBG_ENABLED is not set. Well, actually there might be minimal overhead: there is no overhead when using gcc with a little optimisation (-O3). There is a few bytes overhead with optimisation disabled. (The -O1 level leaves almost no overhead.)

Either way, the rich debugging support is probably worth a few bytes.

Once your program is running, you will want to enable diagnostic levels with dbg::enable, and probably attach an ostream (perhaps cerr) to the diagnostic outputs. See the default states section below for information on the initial state of dbg.

Aside: The standard assert macro is an insidious little devil, a lower case macro. This library replaces it and builds much richer constraints in its place. However, because of it, we have to use an API name dbg::assertion, not dbg::assert - this makes me really cross, but I can't assume that the user does not #include <assert.h> when using <dbg.h> .

Using constraints

The dbg library constraints are very easy to use. Each debugging utility is documented fully to help you understand how they work. Here are some simple examples of library use for run-time constraint checking:

     void test_dbg()
     {
         dbg::trace trace(DBG_HERE);

         int  i   = 5;
         int *ptr = &i;

         dbg::assertion(DBG_ASSERTION(i != 6));
         dbg::check_ptr(ptr, DBG_HERE);

         if (i == 5)
         {
             return;
         }

         // Shouldn't get here
         dbg::sentinel(DBG_HERE);
     }

The constraints provided by dbg are:

• dbg::assertion - General purpose assertion (a better assert)
• dbg::sentinel - Marker for "shouldn't get here" points
• dbg::unimplemented - Marks unimplemented code
• dbg::check_ptr - Zero pointer check
• dbg::check_bounds - Array bounds checking
• dbg::post_mem_fun - Member function post condition
• dbg::post - General function post condition
• dbg::compile_assertion - Compile time assertion

You can modify constraint behaviour with:

• dbg::set_assertion_behaviour - Set how constraints behave
• dbg::set_assertion_period - Set up trigger periods

See their individual documentation for further details on usage.

You can specify whether constraints merely report a warning, cause an exception to be thrown, or immediately abort the program (see dbg::assertion_behaviour).

For assertions that may fire many times in a tight loop, there is the facility to time-restrict output (see dbg::set_assertion_period)

Using logging

All the constraint checking shown above integrates with the dbg library stream logging mechanisms. These logging facilities are open for your use as well.

Here is a simple example of this:

     dbg::attach_ostream(dbg::info, cout);
     // now all 'info' messages go to cout

     dbg::out(dbg::info)    << "This is some info I want to print out\n";

     dbg::out(dbg::tracing) << dbg::indent()
                            << "This is output at 'tracing' level, indented "
                            << "to the same level as the current tracing "
                            << "indent.\n";

When you build without the DBG_ENABLED flag specified, these logging messages will compile out to nothing.

The logging is a very flexible system. You can attach multiple ostreams to any dbg output, so you can easily log to a file and log to the console, for example. The output can be formatted in a number of different ways to suit your needs.

The logging mechanisms provide you with the ability to prepend to all diagnostic output a standard prefix (see dbg::set_prefix), and also to add the diagnostic level and current time to the prefix (see dbg::enable_level_prefix and dbg::enable_time_prefix).

The logging facilities provide by dbg include:

• dbg::enable - Enable/disable activity
• dbg::out - Returns a diagnostic ostream
• dbg::attach_ostream - Attach an ostream to diagnostic output
• dbg::detach_ostream - Detach an ostream to diagnostic output
• dbg::trace - Trace entry/exit points

The output formatting utilities include:

• dbg::set_prefix - Sets the diagnostic output "margin"
• dbg::enable_level_prefix - More information in messages
• dbg::enable_time_prefix - Prints time in messages

Diagnostic sources

The dbg library allows you to differentiate different "sources" of logging.

Each of the debug utilities has a second form in which you can supply a string describing the source of the diagnostic output (see dbg::dbg_source). This source may be a different software component, a separate file - whatever granularity you like!

If you don't specify a dbg::dbg_source then you are working with the ordinary "unnamed" source.

Using these forms you can filter out diagnostics from the different parts of your code. Each source can also be attached to a different set of streams (logging each component to a separate file, for example). The filtering is rich - you can selectively filter each different diagnostic dbg::level for each dbg::dbg_source. For example,

     dbg::enable(dbg::all, "foo-driver", true);
     dbg::enable(dbg::all, "bar-driver", false);

     int i = 5;
     dbg::assertion("foo-driver", DBG_ASSERTION(i != 6));
     dbg::assertion("bar-driver", DBG_ASSERTION(i != 6));

This will trigger an assertion for the "foo-driver" but not the "bar-driver".

There is no requirement to "register" a dbg::dbg_source. The first time you use it in any of the dbg APIs, it will be registered with the dbg library. It comes into an existence as a copy of the "default" debugging source, dbg::default_source.

The default source initially has all debug levels disabled. You can change that with this call. Note that this function only affects sources created after the call is made. Existing sources are unaffected.

If you don't know all of the dbg::dbg_source sources currently available, you can blanket enable/disable them with dbg::enable_all.

It can be tedious to specify the dbg_source in every dbg call in a source file. For this reason, you can specify the DBG_SOURCE compile time macro (wherever you specify DBG_ENABLED). When set, the calls automatically receive the source name via the DBG_HERE macro (see dbg::source_pos for details). If DBG_SOURCE is supplied but you call a dbg API with a specific named dbg_source, this name will override the underlying DBG_SOURCE name.

Overloads

Each constraint utility has a number of overloaded forms. This is to make using them more convenient. The most rich overload allows you to specify a diagnostic dbg::level and a dbg::dbg_source. There are other versions that omit one of these parameters, assuming a relevant default.

Default states

When your program first starts up the dbg library has all debugging levels switched off. You can enable debugging with dbg::enable. All of the possible dbg::dbg_source enables are also all off for all levels. You can enable these with dbg::enable, or dbg::enable_all.

Initially, the std::cerr stream is attached to the dbg::error and dbg::fatal diagnostic levels. You can attach ostreams to the other diagnostic levels with dbg::attach_ostream.

You can modify the "default state" of newly created debug sources. To do this use the special dbg::default_source source name in calls to dbg::enable, dbg::attach_ostream, and and detach_ostream. New sources take the setup from this template source.

All assertion levels are set to dbg::assertions_abort at first, like the standard library's assert macro. You can change this behaviour with dbg::set_assertion_behaviour. There are no timeout periods set - you can change this with dbg::set_assertion_period.

The various predefined debugging levels. The dbg API calls use these levels as parameters, and allow the user to sift the less interesting debugging levels out through dbg::enable.

These levels (and their intended uses) are:

• info - Informational, just for interest
• warning - For warnings, bad things but recoverable
• error - For errors that can't be recovered from
• fatal - Errors at this level will cause the dbg library to abort program execution, no matter what the assertion_behaviour is set to
• tracing - Program execution tracing messages
• debug - Messages about the state of dbg library, you cannot generate messages at this level
• none - For APIs that use 'no level specified'
• all - Used in enable and attach_ostream to specify all levels

This enum type describes what happens when a debugging assertion fails. The behaviour can be:

• assertions_abort - Assertions cause a program abort
• assertions_throw - Assertions cause a dbg_exception to be thrown
• assertions_continue - Assertions cause the standard diagnostic printout to occur (the same as the above behaviours) but execution continues regardless

The dbg library defaults to assertions_abort behaviour, like the standard C assert.

See also: set_assertion_behaviour

typedef for a string that describes the "source" of a diagnostic. If you are working on a large project with many small code modules you may only want to enable debugging from particular source modules. This typedef facilitates this.

Depending on the desired granularity of your dbg sources you will use different naming conventions. For example, your dbg_sources might be filenames, that way you can switch off all debugging output from a particular file quite easily. It might be device driver names, component names, library names, or even function names. It's up to you.

If you provide the DBG_SOURCE macro definition at compile time, then the DBG_HERE macro includes this source name, differentiating the sources for you automatically.

See also: enable_all, dbg_source, bool), dbg::enable_all

Typedef used in the source_pos data structure.

Describes a line number in a source file.

See also: source_pos

Typedef used in the source_pos data structure.

Describes a function name in a source file. (Can be zero to indicate the function name cannot be ascertained on this compiler).

See also: source_pos

Typedef used in the source_pos data structure.

Describes a filename.

See also: source_pos

Data structure describing a position in the source file. That is,

• The line number
• The function name (if the compiler supports this)
• The filename
• The dbg_soruce specified by DBG_SOURCE compilation parameter, if any (otherwise zero)

To create a source_pos for the current position, you can use the DBG_HERE convenience macro.

There is an empty constructor that allows you to create a source_pos that represents 'no position specified'.

This structure should only be used in dbg library API calls.

You can print a source_pos using the usual stream manipulator syntax.

The dbgclock_t typedef is an unfortunate workaround for compatibility purposes. One (unnamed) popular compiler platform supplies a header file, but this header does NOT place the contents into the std namespace.

This typedef is the most elegant work around for that problem. It is conditionally set to the appropriate clock_t definition.

In an ideal world this would not exist.

This is the version for sane, standards-compliant platforms.

See dbgclock_t documentation above. This is the version for broken compiler platforms.

The base type of exception thrown by dbg assertions (and other dbg library constraint checks) if the assertion_behaviour is set to assertions_throw.

The exception keeps a record of the source position of the trigger for this exception.

The type of exception thrown by assertion.

See also: assertion

The type of exception thrown by sentinel.

See also: sentinel

The type of exception thrown by unimplemented.

See also: unimplemented

The type of exception thrown by check_ptr.

See also: check_ptr

Enables or disables a particular debugging level. The affects dbg library calls which don't specify a dbg_source, i.e. from the unnamed source.

Enabling affects both constraint checking and diagnostic log output.

If you enable a debugging level twice you only need to disable it once.

All diagnostic output is initially disabled. You can easily enable output in your main() thus:

     dbg::enable(dbg::all, true);

Note that if dbg library calls do specify a dbg_source, or you provide a definition for the DBG_SOURCE macro on compilation, then you will instead need to enable output for that particular source. Use the overloaded version of enable. This version of enable doesn't affect these other dbg_source calls.

Parameters:

lvl	Diagnostic level to enable/disable
enabled	true to enable this diagnostic level, false to disable it

See also: enable_all, out, attach_ostream

In addition to the above enable function, this overloaded version is used when you use dbg APIs with a dbg_source specified. For these versions of the APIs no debugging will be performed unless you enable it with this API.

To enable debugging for the "foobar" diagnostic source at the info level you need to do the following:

     dbg::enable(dbg::info, "foobar", true);

If you enable a level for a particular dbg_source twice you only need to disable it once.

Parameters:

lvl	Diagnostic level to enable/disable for the dbg_source
src	String describing the diagnostic source
enabled	true to enable this diagnostic level, false to disable it

See also: out

You may not know every single dbg_source that is generating debugging in a particular code base. However, using this function you can enable a diagnostic level for all currently registered sources in one fell swoop.

For example,

     dbg::enable_all(dbg::all, true);

Returns an ostream suitable for sending diagnostic messages to. Each diagnostic level has a different logging ostream which can be enabled/disabled independently. In addition, each dbg_source has separate enables/disables for each diagnostic level.

This overloaded version of out is used when you are creating diagnostics that are tied to a particular dbg_source.

It allows you to write code like this:

     dbg::out(dbg::info, "foobar") << "The foobar is flaky\n";

If you want to prefix your diagnostics with the standard dbg library prefix (see set_prefix) then use the prefix or indent stream manipulators.

Parameters:

lvl	Diagnostic level get get ostream for
src	String describing the diagnostic source

Returns an ostream suitable for sending diagnostic messages to. Each diagnostic level has a different logging ostream which can be enabled/disabled independently.

You use this version of out when you are creating diagnostics that aren't tidied to a particular dbg_source.

Each diagnostic dbg_source has a separate set of streams. This function returns the stream for the "unnamed" source. Use the overload below to obtain the stream for a named source.

It allows you to write code like this:

     dbg::out(dbg::info) << "The code is flaky\n";

If you want to prefix your diagnostics with the standard dbg library prefix (see set_prefix) then use the prefix or indent stream manipulators.

Parameters:

lvl	Diagnostic level get get ostream for

Attaches the specified ostream to the given diagnostic level for the "unnamed" debug source. Now when diagnostics are produced at that level, this ostream will receive a copy.

You can attach multiple ostreams to a diagnostic level. Be careful that they don't go to the same place (e.g. cout and cerr both going to your console) - this might confuse you!

If you attach a ostream multiple times it will only receive one copy of the diagnostics, and you will only need to call detach_ostream once.

Remember, don't destroy the ostream without first removing it from dbg library, or Bad Things will happen.

Parameters:

lvl	Diagnostic level
o	ostream to attach

See also: detach_ostream, detach_all_ostreams

Attaches the specified ostream to the given diagnostic level for the specified debug source. Otherwise, similar to dbg::attach_ostream above.

Parameters:

lvl	Diagnostic level
src	Debug source
o	ostream to attach

See also: detach_ostream, detach_all_ostreams

Detaches the specified ostream from the given diagnostic level.

If the ostream was not attached then no error is generated.

If you attached the ostream twice, one call to detach_ostream will remove it completely.

Parameters:

lvl	Diagnostic level
o	ostream to detach

See also: attach_ostream, detach_all_ostreams

Detaches the specified ostream from the given diagnostic level for the specified debug source. Otherwise, similar to dbg::detach_ostream above.

Parameters:

lvl	Diagnostic level
src	Debug source
o	ostream to detach

See also: attach_ostream, detach_all_ostreams

Detaches all attached ostreams from the specified diagnostic level for the "unnamed" diagnostic source.

Parameters:

lvl	Diagnostic level

See also: attach_ostream, detach_ostream

Detaches all attached ostreams from the specified diagnostic level for the specified debug source. Otherwise, similar to dbg::detach_all_ostreams above.

Parameters:

lvl	Diagnostic level

See also: attach_ostream, detach_ostream

Convenience function that returns the ostream for the info dbg::level for the "unnamed" source.

See also: out

Convenience function that returns the ostream for the warning dbg::level for the "unnamed" source.

See also: out

Convenience function that returns the ostream for the error dbg::level for the "unnamed" source.

See also: out

Convenience function that returns the ostream for the fatal dbg::level for the "unnamed" source.

See also: out

Convenience function that returns the ostream for the tracing dbg::level for the "unnamed" source.

See also: out

Sets the debugging prefix - the characters printed before any diagnostic output. Defaults to "*** ".

Parameters:

prefix

New prefix string

See also: prefix, enable_level_prefix, enable_time_prefix

The dbg library can add to the prefix the name of the used diagnostic level (e.g. info, fatal, etc).

By default, this facility is disabled. This function allows you to enable the facility.

Parameters:

enabled

true to enable level prefixing, false to disable

See also: set_prefix, enable_time_prefix

The dbg library can add to the prefix the current time. This can be useful when debugging systems which remain active for long periods of time.

By default, this facility is disabled. This function allows you to enable the facility.

The time is produced in the format of the standard library ctime function.

Parameters:

enabled

true to enable time prefixing, false to disable

See also: set_prefix, enable_level_prefix

Used so that you can produce a prefix in your diagnostic output in the same way that the debugging library does.

You can use it in one of two ways: with or without a diagnostic level. For the latter, if level prefixing is enabled (see enable_level_prefix) then produces a prefix including the specified diagnostic level text.

Examples of use:

     dbg::out(dbg::info) << dbg::prefix()
                         << "A Bad Thing happened\n";

     dbg::out(dbg::info) << dbg::prefix(dbg::info)
                         << "A Bad Thing happened\n";

See also: indent, set_prefix, enable_level_prefix, enable_time_prefix

This is called when you use the prefix stream manipulator.

See also: prefix

Used so that you can indent your diagnostic output to the same level as the debugging library. This also produces the prefix output.

Examples of use:

     dbg::out(dbg::info) << dbg::indent()
                         << "A Bad Thing happened\n";

     dbg::out(dbg::info) << dbg::indent(dbg::info)
                         << "A Bad Thing happened\n";

See also: prefix, set_prefix, enable_level_prefix, enable_time_prefix

This is called when you use the indent stream manipulator.

See also: indent

This is called when you send a source_pos to a diagnostic output. You can use this to easily check the flow of execution in your program.

For example,

     dbg::out(dbg::tracing) << DBG_HERE << std::endl;

Take care that you only send DBG_HERE to the diagnostic outputs (obtained with dbg::out) and not "ordinary" streams like std::cout.

In non debug builds, DBG_HERE is a "no-op" doing nothing, and so no useful output will be produced on cout.

See also: indent

Sets what happens when assertions (or other constraints) trigger. There will always be diagnostic output. Assertions have 'abort' behaviour by default - like the ISO C standard, they cause an abort.

If an assertion is encountered at the fatal level, the debugging library will abort the program regardless of this behaviour setting.

If a diagnostic level is not enabled (see enable) then the assertion_behaviour is not enacted, and no output is produced.

Parameters:

lvl	Diagnostic level to set behaviour for
behaviour	Assertion behaviour

See also: set_assertion_period, enable, assertion, sentinel, unimplemented, check_ptr

You may want an assertion to trigger once only and then for subsequent calls to remain inactive. For example, if there is an assertion in a loop you may not want diagnostics produced for each loop iteration.

To do this, you do the following:

      // Prevent several thousand diagnostic print outs
      dbg::set_assertion_period(CLOCKS_PER_SEC);

      // Example loop
      int array[LARGE_VALUE];
      put_stuff_in_array(array);
      for(unsigned int n = 0; n < LARGE_VALUE; n++)
      {
          dbg::assertion(DBG_ASSERT(array[n] != 0));
          do_something(array[n]);
      }

set_assertion_period forces a certain time period between triggers of a particular constraint. The assertion in the example above will only be triggered once a second (despite the fact that the constraint condition will be broken thousands of times a second). This will not affect any other assertion - they will each have their own timeout periods.

Setting a period of zero disables any constraint period.

The default behaviour is to have no period.

If a period is set then diagnostic printouts will include the number of times each constraint has been triggered (since the period was set). Using this, even if diagnostics don't always appear on the attached ostreams you have some indication of how often each constraint is triggered.

This call only really makes sense if the assertion_behaviour is set to assertions_continue.

Parameters:

period

Time between triggerings of each assertion, or zero to disable

See also: set_assertion_behaviour, assertion, sentinel, unimplemented, check_ptr

Describes an assertion.

This is an internal data structure, you do not need to create it directly. Use the DBG_ASSERTION macro to create it.

See also: assertion

Used to assert a constraint in your code. Use the DBG_ASSERTION macro to generate the third parameter.

This version creates an assertion bound to a particular dbg_source.

The assertion is the most general constraint utility - there are others which have more specific purposes (like check_ptr to ensure a pointer is non-null). assertion allows you to test any boolean expression.

To use assertion for a dbg_source "foobar" you write code like:

     int i = 0;
     dbg::assertion(info, "foobar", DBG_ASSERTION(i != 0));

If you build with debugging enabled (see dbg) the program will produce diagnostic output to the relevant output stream if the constraint fails, and the appropriate assertion_behaviour is enacted.

Since in non-debug builds the expression in the DBG_ASSERTION macro will not be evaluated, it is important that the expression has no side effects.

Parameters:

lvl	Diagnostic level to assert at
src	String describing the diagnostic source
ai	assert_info structure created with DBG_ASSERTION

Overloaded version of assertion that is not bound to a particular dbg_source.

Parameters:

lvl	Diagnostic level to assert at
ai	assert_info structure created with DBG_ASSERTION

Overloaded version of assertion that defaults to the warning level.

Parameters:

src	String describing the diagnostic source
ai	assert_info structure created with DBG_ASSERTION

Overloaded version of assertion that defaults to the warning level and is not bound to a particular dbg_source.

Parameters:

ai	assert_info structure created with DBG_ASSERTION

You should put this directly after a "should never get here" comment.

      int i = 5;
      if (i == 5)
      {
          std::cout << "Correct program behaviour\n";
      }
      else
      {
          dbg::sentinel(dbg::error, "foobar", DBG_HERE);
      }

Parameters:

lvl	Diagnostic level to assert at
src	String describing the diagnostic source
here	Supply DBG_HERE

Overloaded version of sentinel that is not bound to a particular dbg_source.

Parameters:

lvl	Diagnostic level to assert at
here	Supply DBG_HERE

Overloaded version of sentinel that defaults to the warning level and is not bound to a particular dbg_source.

Parameters:

src	String describing the diagnostic source
here	Supply DBG_HERE

Overloaded version of sentinel that defaults to the warning level and is not bound to a particular dbg_source.

Parameters:

here	Supply DBG_HERE

You should put this directly after a "this has not been implemented (yet)" comment.

      switch (variable)
      {
          ...
          case SOMETHING:
          {
              dbg::unimplemented(dbg::warning, "foobar", DBG_HERE);
              break;
          }
          ...
      }

Note the "break;" above - if the assertion_behaviour is non-fatal then execution will continue. You wouldn't want unintentional fall-through.

Parameters:

lvl	Diagnostic level to assert at
src	String describing the diagnostic source
here	Supply DBG_HERE

Overloaded version of unimplemented that is not bound to a particular dbg_source.

Parameters:

lvl	Diagnostic level to assert at
here	Supply DBG_HERE

Overloaded version of unimplemented that defaults to the warning level.

Parameters:

src	String describing the diagnostic source
here	Supply DBG_HERE

Overloaded version of unimplemented that defaults to the warning level and is not bound to a particular dbg_source.

Parameters:

here	Supply DBG_HERE

A diagnostic function to assert that a pointer is not zero.

To use it you write code like:

     void *p = 0;
     dbg::check_ptr(dbg::info, "foobar", p, DBG_HERE);

It's better to use this than a general purpose assertion. It reads far more intuitively in your code.

Parameters:

lvl	Diagnostic level to assert at
src	String describing the diagnostic source
p	Pointer to check
here	Supply DBG_HERE

Overloaded version of check_ptr that is not bound to a particular dbg_source.

Parameters:

lvl	Diagnostic level to assert at
p	Pointer to check
here	Supply DBG_HERE

Overloaded version of check_ptr that defaults to the warning level.

Parameters:

src	String describing the diagnostic source
p	Pointer to check
here	Supply DBG_HERE

Overloaded version of check_ptr that defaults to the warning level and is not bound to a particular dbg_source.

Parameters:

p	Pointer to check
here	Supply DBG_HERE

Utility that determines the number of elements in an array. Used by the check_bounds constraint utility function.

This is not available in non-debug versions, so do not use it directly.

Parameters:

array

Array to determine size of

Returns: The number of elements in the array

A diagnostic function to assert that an array access is not out of bounds.

You probably want to use the more convenient check_bounds versions below if you are accessing an array whose definition is in scope - the compiler will then safely determine the size of the array for you.

Parameters:

lvl	Diagnostic level to assert at
src	String describing the diagnostic source
index	Test index
bound	Boundary value (index must be < bound, and >= 0)
here	Supply DBG_HERE

A diagnostic function to assert that an array access is not out of bounds. With this version you can specify the minimum and maximum bound value.

You probably want to use the more convenient check_bounds version below if you are accessing an array whose definition is in scope - the compiler will then safely determine the size of the array for you.

Parameters:

lvl	Diagnostic level to assert at
src	String describing the diagnostic source
index	Test index
minbound	Minimum bound (index must be >= minbound
maxbound	Minimum bound (index must be < maxbound)
here	Supply DBG_HERE

Overloaded version of check_bounds that can automatically determine the size of an array if it within the current scope.

You use it like this:

     int a[10];
     int index = 10;
     dbg::check_bounds(dbg::error, index, a, DBG_HERE);
     a[index] = 5;

Parameters:

lvl	Diagnostic level to assert at
src	String describing the diagnostic source
index	Test index
array	Array index is applied to
here	Supply DBG_HERE

Overloaded version of check_bounds that is not bound to a particular dbg_source.

Parameters:

lvl	Diagnostic level to assert at
index	Test index
array	Array index is applied to
here	Supply DBG_HERE

Overloaded version of check_bounds that defaults to the warning level.

Parameters:

src	String describing the diagnostic source
index	Test index
array	Array index is applied to
here	Supply DBG_HERE

Overloaded version of check_bounds that defaults to the warning level and is not bound to a particular dbg_source.

Parameters:

index	Test index
array	Array index is applied to
here	Supply DBG_HERE

The trace class allows you to easily produce tracing diagnostics.

When the ctor is called, it prints "->" and the name of the function, increasing the indent level. When the object is deleted it prints "<-" followed again by the name of the function.

You can use the name of the current function gathered via the DBG_HERE macro, or some other tracing string you supply.

Diagnostics are produced at the tracing level.

For example, if you write the following code:

     void foo()
     {
         dbg::trace t1(DBG_HERE);
         // do some stuff
         {
             dbg::trace t2("sub block");
             // do some stuff
             dbg::out(tracing) << dbg::prefix() << "Hello!\n";
         }
         dbg::out(tracing) << dbg::prefix() << "Hello again!\n";
         // more stuff
     }

You will get the following tracing information:

     *** ->foo (0 in foo.cpp)
     ***   ->sub block
     ***     Hello!
     ***   <-sub block
     ***   Hello again!
     *** <-foo (0 in foo.cpp)

Don't forget to create named dbg::trace objects. If you create anonymous objects (i.e. you just wrote "dbg::trace(DBG_HERE);") then the destructor will be called immediately, rather than at the end of the block scope, causing invalid trace output.

Tracing does not cause assertions to trigger, therefore you will never generate an abort or exception using this object.

If you disable the tracing diagnostic level before the trace object's destructor is called you will still get the closing trace output. This is important, otherwise the indentation level of the library would get out of sync. In this case, the closing diagnostic output will have a "note" attached to indicate what has happened.

Similarly, if tracing diagnostics are off when the trace object is created, yet subsequently enabled before the destructor there will be no closing tracing output.

A post condition class. This utility automates the checking of post conditions using assertion. It requires a member function with the signature:

     bool some_class::invariant() const;

When you create a post_mem_fun object you specify a post condition member function. When the post_mem_fun object is destroyed the postcondition is asserted.

This is useful for methods where there are a number of exit points which would make it tedious to put the same dbg::assertion in multiple places.

It is also handy when an exception might be thrown and propagated by a function, ensuring that a postcondition is first checked. Bear in mind that Bad Things can happen if the assertion_behaviour is assertions_throw and this is triggered via a propagating exception.

An example of usage, the do_test method below uses the post_mem_fun object:

     class test
     {
         public:
             test() : a(10) {}
             do_test()
             {
                 dbg::post_mem_fun
                    post(dbg::info, this, &test::invariant, DBG_HERE);
                 a = 9;
                 if (SOME_CONDITION)
                 {
                     return;                                      // (*)
                 }
                 else if (SOME_OTHER_CONDITION)
                 {
                     throw std::exception();                      // (*)
                 }
                                                                  // (*)
             }
         private:
             bool invariant()
             {
                 return a == 10;
             }
             int a;
     };

The post condition will be asserted at each point marked (*).

See also: post

A post condition class. Unlike post_mem_fun, this class calls a non-member function with signature:

     bool some_function();

Otherwise, use it identically to the post_mem_fun.

See also: post_mem_fun

If we need to assert a constraint that can be calculated at compile time, then it would be advantageous to do so - moving error detection to an earlier phase in development is always a Good Thing.

This utility allows you to do this. You use it like this:

     enum { foo = 4, bar = 6 };
     compile_assertion<(foo > bar)>();

There is a particular point to observe here. Although the expression is now a template parameter, it is important to contain it in parentheses. This is simply because the expression contains a ">" which otherwise would be taken by the compiler to be the closing of the template parameter. Although not all expressions require this, it is good practice to do it at all times.

In non-debug versions, this class is used to replace an ostream so that code will compile away. Do not use it directly.

• Version: 1.20
• Author: Pete Goodliffe
• Generated: pg1 on imgpc030 on Tue Sep 16 13:46:16 2003, using kdoc 2.0a54.