dune-common 2.9.0
Loading...
Searching...
No Matches
Modules | Files | Classes | Typedefs | Functions | Variables
Debug output
Collaboration diagram for Debug output:

Modules

 Standard Debug Streams
 

Files

file  debugstream.hh
 Defines several output streams for messages of different importance.
 

Classes

struct  Dune::greater_or_equal< current, threshold >
 Greater or equal template test. More...
 
struct  Dune::common_bits< current, mask >
 activate if current and mask have common bits switched on. More...
 
class  Dune::DebugStreamError
 standard exception for the debugstream More...
 
class  Dune::StreamWrap
 
class  Dune::DebugStreamState
 Intermediate class to implement tie-operation of DebugStream. More...
 
class  Dune::DebugStream< thislevel, dlevel, alevel, activator >
 Generic class to implement debug output streams. More...
 

Typedefs

typedef unsigned int Dune::DebugLevel
 Type for debug levels.
 

Functions

 Dune::StreamWrap::StreamWrap (std::ostream &_out)
 
 Dune::DebugStream< thislevel, dlevel, alevel, activator >::DebugStream (std::ostream &out=std::cerr)
 Create a DebugStream and set initial output stream.
 
 Dune::DebugStream< thislevel, dlevel, alevel, activator >::DebugStream (DebugStreamState &master, std::ostream &fallback=std::cerr)
 Create a DebugStream and directly tie to another DebugStream.
 
 Dune::DebugStream< thislevel, dlevel, alevel, activator >::~DebugStream ()
 Destroy stream.
 
template<class T >
DebugStreamDune::DebugStream< thislevel, dlevel, alevel, activator >::operator<< (const T data)
 Generic types are passed on to current output stream.
 
DebugStreamDune::DebugStream< thislevel, dlevel, alevel, activator >::operator<< (const int data)
 explicit specialization so that enums can be printed
 
DebugStreamDune::DebugStream< thislevel, dlevel, alevel, activator >::operator<< (std::ostream &(*f)(std::ostream &))
 pass on manipulators to underlying output stream
 
DebugStreamDune::DebugStream< thislevel, dlevel, alevel, activator >::flush ()
 pass on flush to underlying output stream
 
void Dune::DebugStream< thislevel, dlevel, alevel, activator >::push (bool b)
 set activation flag and store old value
 
void Dune::DebugStream< thislevel, dlevel, alevel, activator >::pop ()
 restore previously set activation flag
 
bool Dune::DebugStream< thislevel, dlevel, alevel, activator >::active () const
 reports if this stream will produce output
 
void Dune::DebugStream< thislevel, dlevel, alevel, activator >::attach (std::ostream &stream)
 set output to a different stream.
 
void Dune::DebugStream< thislevel, dlevel, alevel, activator >::detach ()
 detach current output stream and restore to previous stream
 
void Dune::DebugStream< thislevel, dlevel, alevel, activator >::tie (DebugStreamState &to)
 Tie a stream to this one.
 
void Dune::DebugStream< thislevel, dlevel, alevel, activator >::untie ()
 Untie stream.
 

Variables

static constexpr bool Dune::greater_or_equal< current, threshold >::value = (current >= threshold)
 
static constexpr bool Dune::common_bits< current, mask >::value = ((current & mask) != 0)
 
std::ostream & Dune::StreamWrap::out
 
StreamWrapDune::StreamWrap::next
 
StreamWrapDune::DebugStreamState::current
 current output stream and link to possibly pushed old output streams
 
bool Dune::DebugStreamState::_active
 flag to switch output during runtime
 
bool Dune::DebugStreamState::_tied
 are we tied to another DebugStream?
 
unsigned int Dune::DebugStreamState::_tied_streams
 how many streams are tied to this state
 

Detailed Description

The debug output is implemented by instances of DebugStream which provides the following features:

The Dune-components should use the streams explained in Standard Debug Streams for output so that applications may redirect the output globally.

Changes in runtime are provided by three sets of methods:

The first methods implement a full stack whereas tie() is a bit different: though a tied stream may be (de)activated via push()/pop() you cannot attach() or detach() an output. You'll need to change the master stream instead.

Applications

Applications using the Dune-library should create an independent set of DebugStreams so that the debug levels can be changed separately. Example:

static const Dune::DebugLevel APPL_MINLEVEL = 3;
unsigned int DebugLevel
Type for debug levels.
Definition debugstream.hh:118
Generic class to implement debug output streams.
Definition debugstream.hh:192

This code creates three streams of which only the last one really creates output. The output-routines of the other streams vanish in optimized executables.

You can use the common_bits-Template to switch to a policy using bitflags:

enum { APPL_CORE = 1, APPL_IO = 2, APPL_GRAPHICS = 4};
static const Dune::DebugLevel APPL_DEBUG_MASK = APPL_CORE | APPL_GRAPHICS;
static const Dune::DebugLevel APPL_ACTIVE_MASK = 0xff;

Applications that wish to redirect the Standard Debug Streams through their private streams may use the tie()-mechanism:

// initialize streams like above
Dune::dwarn.tie(coreout);
// ... Dune-output to dwarn will be directed through coreout ...
void untie()
Untie stream.
Definition debugstream.hh:413
void tie(DebugStreamState &to)
Tie a stream to this one.
Definition debugstream.hh:397
DWarnType dwarn(std::cerr)
Stream for warnings indicating problems.
Definition stdstreams.hh:161

Keep in mind to untie() a stream before the tied stream is destructed.

An alternative is to attach() an output stream defined by the application:

std::ofstream mylog("application.log");
void attach(std::ostream &stream)
set output to a different stream.
Definition debugstream.hh:371

standard debug streams with level below MINIMAL_DEBUG_LEVEL will collapse to doing nothing if output is requested.

MINIMAL_DEBUG_LEVEL is set to DUNE_MINIMAL_DEBUG_LEVEL, which is defined in config.h and can be changed by the configure option

--with-minimal-debug-level=[grave|warn|info|verb|vverb]

For a Dune-Release this should be set to at least 4 so that only important messages are active. Dune-developers may adapt this setting to their debugging needs locally

Keep in mind that libdune has to be recompiled if this value is changed!

The singleton instances of the available debug streams can be found in the Standard Debug Streams module

Typedef Documentation

◆ DebugLevel

typedef unsigned int Dune::DebugLevel

Type for debug levels.

Only positive values allowed

Function Documentation

◆ active()

template<DebugLevel thislevel = 1, DebugLevel dlevel = 1, DebugLevel alevel = 1, template< DebugLevel, DebugLevel > class activator = greater_or_equal>
bool Dune::DebugStream< thislevel, dlevel, alevel, activator >::active ( ) const
inline

reports if this stream will produce output

a DebugStream that is deactivated because of its level will always return false, otherwise the state of the internal activation is returned

◆ attach()

template<DebugLevel thislevel = 1, DebugLevel dlevel = 1, DebugLevel alevel = 1, template< DebugLevel, DebugLevel > class activator = greater_or_equal>
void Dune::DebugStream< thislevel, dlevel, alevel, activator >::attach ( std::ostream &  stream)
inline

set output to a different stream.

Old stream data is stored

◆ DebugStream() [1/2]

template<DebugLevel thislevel = 1, DebugLevel dlevel = 1, DebugLevel alevel = 1, template< DebugLevel, DebugLevel > class activator = greater_or_equal>
Dune::DebugStream< thislevel, dlevel, alevel, activator >::DebugStream ( DebugStreamState master,
std::ostream &  fallback = std::cerr 
)
inline

Create a DebugStream and directly tie to another DebugStream.

The fallback is used if a DebugStream constructed via this method is untie()ed later. Otherwise the stream would be broken afterwards.

◆ DebugStream() [2/2]

template<DebugLevel thislevel = 1, DebugLevel dlevel = 1, DebugLevel alevel = 1, template< DebugLevel, DebugLevel > class activator = greater_or_equal>
Dune::DebugStream< thislevel, dlevel, alevel, activator >::DebugStream ( std::ostream &  out = std::cerr)
inline

Create a DebugStream and set initial output stream.

during runtime another stream can be attach()ed, however the initial stream may not be detach()ed.

◆ detach()

template<DebugLevel thislevel = 1, DebugLevel dlevel = 1, DebugLevel alevel = 1, template< DebugLevel, DebugLevel > class activator = greater_or_equal>
void Dune::DebugStream< thislevel, dlevel, alevel, activator >::detach ( )
inline

detach current output stream and restore to previous stream

Exceptions
DebugStreamError

◆ flush()

template<DebugLevel thislevel = 1, DebugLevel dlevel = 1, DebugLevel alevel = 1, template< DebugLevel, DebugLevel > class activator = greater_or_equal>
DebugStream & Dune::DebugStream< thislevel, dlevel, alevel, activator >::flush ( )
inline

pass on flush to underlying output stream

◆ operator<<() [1/3]

template<DebugLevel thislevel = 1, DebugLevel dlevel = 1, DebugLevel alevel = 1, template< DebugLevel, DebugLevel > class activator = greater_or_equal>
DebugStream & Dune::DebugStream< thislevel, dlevel, alevel, activator >::operator<< ( const int  data)
inline

explicit specialization so that enums can be printed

Operators for built-in types follow special rules (ยง11.2.3) so that enums won't fit into the generic method above. With an existing operator<< for int however the enum will be automatically casted.

◆ operator<<() [2/3]

template<DebugLevel thislevel = 1, DebugLevel dlevel = 1, DebugLevel alevel = 1, template< DebugLevel, DebugLevel > class activator = greater_or_equal>
template<class T >
DebugStream & Dune::DebugStream< thislevel, dlevel, alevel, activator >::operator<< ( const T  data)
inline

Generic types are passed on to current output stream.

◆ operator<<() [3/3]

template<DebugLevel thislevel = 1, DebugLevel dlevel = 1, DebugLevel alevel = 1, template< DebugLevel, DebugLevel > class activator = greater_or_equal>
DebugStream & Dune::DebugStream< thislevel, dlevel, alevel, activator >::operator<< ( std::ostream &(*)(std::ostream &)  f)
inline

pass on manipulators to underlying output stream

◆ pop()

template<DebugLevel thislevel = 1, DebugLevel dlevel = 1, DebugLevel alevel = 1, template< DebugLevel, DebugLevel > class activator = greater_or_equal>
void Dune::DebugStream< thislevel, dlevel, alevel, activator >::pop ( )
inline

restore previously set activation flag

Exceptions
DebugStreamError

◆ push()

template<DebugLevel thislevel = 1, DebugLevel dlevel = 1, DebugLevel alevel = 1, template< DebugLevel, DebugLevel > class activator = greater_or_equal>
void Dune::DebugStream< thislevel, dlevel, alevel, activator >::push ( bool  b)
inline

set activation flag and store old value

◆ StreamWrap()

Dune::StreamWrap::StreamWrap ( std::ostream &  _out)
inline

◆ tie()

template<DebugLevel thislevel = 1, DebugLevel dlevel = 1, DebugLevel alevel = 1, template< DebugLevel, DebugLevel > class activator = greater_or_equal>
void Dune::DebugStream< thislevel, dlevel, alevel, activator >::tie ( DebugStreamState to)
inline

Tie a stream to this one.

Exceptions
DebugStreamError

◆ untie()

template<DebugLevel thislevel = 1, DebugLevel dlevel = 1, DebugLevel alevel = 1, template< DebugLevel, DebugLevel > class activator = greater_or_equal>
void Dune::DebugStream< thislevel, dlevel, alevel, activator >::untie ( )
inline

Untie stream.

Exceptions
DebugStreamError

◆ ~DebugStream()

template<DebugLevel thislevel = 1, DebugLevel dlevel = 1, DebugLevel alevel = 1, template< DebugLevel, DebugLevel > class activator = greater_or_equal>
Dune::DebugStream< thislevel, dlevel, alevel, activator >::~DebugStream ( )
inline

Destroy stream.

If other streams still tie() to this stream the destructor will call std::terminate() because you can hardly recover from this problem and the child streams would certainly break on the next output.

Variable Documentation

◆ _active

bool Dune::DebugStreamState::_active

flag to switch output during runtime

◆ _tied

bool Dune::DebugStreamState::_tied

are we tied to another DebugStream?

◆ _tied_streams

unsigned int Dune::DebugStreamState::_tied_streams

how many streams are tied to this state

◆ current

StreamWrap* Dune::DebugStreamState::current

current output stream and link to possibly pushed old output streams

◆ next

StreamWrap* Dune::StreamWrap::next

◆ out

std::ostream& Dune::StreamWrap::out

◆ value [1/2]

template<DebugLevel current, DebugLevel threshold>
constexpr bool Dune::greater_or_equal< current, threshold >::value = (current >= threshold)
staticconstexpr

◆ value [2/2]

template<DebugLevel current, DebugLevel mask>
constexpr bool Dune::common_bits< current, mask >::value = ((current & mask) != 0)
staticconstexpr