Classes | Public Member Functions | Static Public Member Functions | Private Types | Private Member Functions | Private Attributes

LogStream Class Reference
[Textual output]

Inheritance diagram for LogStream:
Inheritance graph
[legend]

List of all members.

Classes

class  Prefix

Public Member Functions

 LogStream ()
 ~LogStream ()
void attach (std::ostream &o)
void detach ()
void test_mode (bool on=true)
std::ostream & get_console ()
std::ostream & get_file_stream ()
bool has_file () const
void log_cerr ()
const std::string & get_prefix () const
void push (const std::string &text)
void pop ()
unsigned int depth_console (const unsigned int n)
unsigned int depth_file (const unsigned int n)
bool log_execution_time (const bool flag)
bool log_time_differences (const bool flag)
void timestamp ()
bool log_thread_id (const bool flag)
void threshold_double (const double t)
void threshold_float (const float t)
template<typename T >
LogStreamoperator<< (const T &t)
LogStreamoperator<< (const double t)
LogStreamoperator<< (const float t)
LogStreamoperator<< (std::ostream &(*p)(std::ostream &))
std::size_t memory_consumption () const

Static Public Member Functions

::ExceptionBaseExcNoFileStreamGiven ()

Private Types

typedef std::map< unsigned int,
std_cxx1x::shared_ptr
< std::ostringstream > > 
stream_map_type

Private Member Functions

void print_line_head ()
template<typename T >
void print (const T &t)
std::ostringstream & get_stream ()

Private Attributes

std::stack< std::string > prefixes
std::ostream * std_out
std::ostream * file
unsigned int std_depth
unsigned int file_depth
bool print_utime
bool diff_utime
double last_time
double double_threshold
float float_threshold
double offset
bool print_thread_id
double reference_time_val
struct tms reference_tms
std::streambuf * old_cerr
stream_map_type outstreams

Detailed Description

A class that simplifies the process of execution logging. It does so by providing

The usual usage of this class is through the pregenerated object deallog. Typical steps are

LogStream and reproducible regression test output

Generating reproducible floating point output for regression tests is mildly put a nightmare. In order to make life a little easier, LogStream implements a few features that try to achieve such a goal. These features are turned on by calling test_mode(), and it is not recommended to use them in any other environment. Right now, LogStream implements the following:

  1. A double number very close to zero will end up being output in exponential format, although it has no significant digits. The parameter double_threshold determines which numbers are too close to zero to be considered nonzero.
  2. For float numbers holds the same, but with a typically larger float_threshold.
  3. Rounded numbers become unreliable with inexact arithmetics. Therefore, adding a small number before rounding makes results more reproducible, assuming that numbers like 0.5 are more likely than 0.49997.

It should be pointed out that all of these measures distort the output and make it less accurate. Therefore, they are only recommended if the output needs to be reproducible.

Author:
Guido Kanschat, Wolfgang Bangerth, 1999, 2003, 2011

Definition at line 86 of file logstream.h.


Member Typedef Documentation

typedef std::map<unsigned int, std_cxx1x::shared_ptr<std::ostringstream> > LogStream::stream_map_type [private]

Type of the stream map

Definition at line 604 of file logstream.h.


Constructor & Destructor Documentation

LogStream::LogStream (  )

Standard constructor, since we intend to provide an object deallog in the library. Set the standard output stream to std::cerr.

LogStream::~LogStream (  )

Destructor.


Member Function Documentation

void LogStream::attach ( std::ostream &  o )

Enable output to a second stream o.

void LogStream::detach (  )

Disable output to the second stream. You may want to call close on the stream that was previously attached to this object.

void LogStream::test_mode ( bool  on = true )

Setup the logstream for regression test mode.

This sets the parameters double_threshold, float_threshold, and offset to nonzero values. The exact values being used have been determined experimentally and can be found in the source code.

Called with an argument false, switches off test mode and sets all involved parameters to zero.

std::ostream& LogStream::get_console (  )

Gives the default stream (std_out).

std::ostream& LogStream::get_file_stream (  )

Gives the file stream.

bool LogStream::has_file (  ) const
Returns:
true, if file stream has already been attached.
void LogStream::log_cerr (  )

Reroutes cerr to LogStream. Works as a switch, turning logging of cerr on and off alternatingly with every call.

const std::string& LogStream::get_prefix (  ) const

Return the prefix string.

void LogStream::push ( const std::string &  text )
Deprecated:
Use Prefix instead

Push another prefix on the stack. Prefixes are automatically separated by a colon and there is a double colon after the last prefix.

Referenced by SchurMatrix< MA_inverse, MB, MDt, MC >::postprocess(), SchurMatrix< MA_inverse, MB, MDt, MC >::prepare_rhs(), SolverRelaxation< VECTOR >::solve(), EigenInverse< VECTOR >::solve(), EigenPower< VECTOR >::solve(), and SchurMatrix< MA_inverse, MB, MDt, MC >::vmult().

void LogStream::pop (  )
unsigned int LogStream::depth_console ( const unsigned int  n )

Maximum number of levels to be printed on the console. This function allows to restrict console output to the upmost levels of iterations. Only output with less than n prefixes is printed. By calling this function with n=0, no console output will be written.

The previous value of this parameter is returned.

unsigned int LogStream::depth_file ( const unsigned int  n )

Maximum number of levels to be written to the log file. The functionality is the same as depth_console, nevertheless, this function should be used with care, since it may spoile the value of a log file.

The previous value of this parameter is returned.

bool LogStream::log_execution_time ( const bool  flag )

Set time printing flag. If this flag is true, each output line will be prepended by the user time used by the running program so far.

The previous value of this parameter is returned.

bool LogStream::log_time_differences ( const bool  flag )

Output time differences between consecutive logs. If this function is invoked with true, the time difference between the previous log line and the recent one is printed. If it is invoked with false, the accumulated time since start of the program is printed (default behavior).

The measurement of times is not changed by this function, just the output.

The previous value of this parameter is returned.

void LogStream::timestamp (  )

Write detailed timing information.

bool LogStream::log_thread_id ( const bool  flag )

Log the thread id.

void LogStream::threshold_double ( const double  t )

Set a threshold for the minimal absolute value of double values. All numbers with a smaller absolute value will be printed as zero.

The default value for this threshold is zero, i.e. numbers are printed according to their real value.

This feature is mostly useful for automated tests: there, one would like to reproduce the exact same solution in each run of a testsuite. However, subtle difference in processor, operating system, or compiler version can lead to differences in the last few digits of numbers, due to different rounding. While one can avoid trouble for most numbers when comparing with stored results by simply limiting the accuracy of output, this does not hold for numbers very close to zero, i.e. zero plus accumulated round-off. For these numbers, already the first digit is tainted by round-off. Using the present function, it is possible to eliminate this source of problems, by simply writing zero to the output in this case.

void LogStream::threshold_float ( const float  t )

The same as threshold_double(), but for float values.

template<class T >
LogStream & LogStream::operator<< ( const T &  t ) [inline]

Output a constant something through this stream.

Definition at line 642 of file logstream.h.

References print().

LogStream & LogStream::operator<< ( const double  t ) [inline]

Output double precision numbers through this stream.

If they are set, this function applies the methods for making floating point output reproducible as discussed in the introduction.

Definition at line 654 of file logstream.h.

References double_threshold, offset, and print().

LogStream & LogStream::operator<< ( const float  t ) [inline]

Output single precision numbers through this stream.

If they are set, this function applies the methods for making floating point output reproducible as discussed in the introduction.

Definition at line 679 of file logstream.h.

References float_threshold, offset, and print().

LogStream& LogStream::operator<< ( std::ostream &(*)(std::ostream &)  p )

Treat ostream manipulators. This passes on the whole thing to the template function with the exception of the std::endl manipulator, for which special action is performed: write the temporary stream buffer including a header to the file and std::cout and empty the buffer.

An overload of this function is needed anyway, since the compiler can't bind manipulators like std::endl directly to template arguments T like in the previous general template. This is due to the fact that std::endl is actually an overloaded set of functions for std::ostream, std::wostream, and potentially more of this kind. This function is therefore necessary to pick one element from this overload set.

std::size_t LogStream::memory_consumption (  ) const

Determine an estimate for the memory consumption (in bytes) of this object. Since sometimes the size of objects can not be determined exactly (for example: what is the memory consumption of an STL std::map type with a certain number of elements?), this is only an estimate. however often quite close to the true value.

::ExceptionBase& LogStream::ExcNoFileStreamGiven (  ) [static]

Exception.

void LogStream::print_line_head (  ) [private]

Print head of line. This prints optional time information and the contents of the prefix stack.

template<class T >
void LogStream::print ( const T &  t ) [inline, private]

Actually do the work of writing output. This function unifies the work that is common to the two operator<< functions.

Definition at line 622 of file logstream.h.

References get_stream().

Referenced by operator<<().

std::ostringstream& LogStream::get_stream (  ) [private]

Check if we are on a new line and print the header before the data.

Referenced by print().


Member Data Documentation

std::stack<std::string> LogStream::prefixes [private]

Stack of strings which are printed at the beginning of each line to allow identification where the output was generated.

Definition at line 445 of file logstream.h.

std::ostream* LogStream::std_out [private]

Default stream, where the output is to go to. This stream defaults to std::cerr, but can be set to another stream through the constructor.

Definition at line 453 of file logstream.h.

std::ostream* LogStream::file [private]

Pointer to a stream, where a copy of the output is to go to. Usually, this will be a file stream.

You can set and reset this stream by the attach function.

Definition at line 463 of file logstream.h.

Value denoting the number of prefixes to be printed to the standard output. If more than this number of prefixes is pushed to the stack, then no output will be generated until the number of prefixes shrinks back below this number.

Definition at line 475 of file logstream.h.

Same for the maximum depth of prefixes for output to a file.

Definition at line 481 of file logstream.h.

Flag for printing execution time.

Definition at line 486 of file logstream.h.

Flag for printing time differences.

Definition at line 491 of file logstream.h.

Time of last output line.

Definition at line 496 of file logstream.h.

Threshold for printing double values. Every number with absolute value less than this is printed as zero.

Definition at line 504 of file logstream.h.

Referenced by operator<<().

float LogStream::float_threshold [private]

Threshold for printing float values. Every number with absolute value less than this is printed as zero.

Definition at line 512 of file logstream.h.

Referenced by operator<<().

An offset added to every float or double number upon output. This is done after the number is compared to double_threshold or float_threshold, but before rounding.

This functionality was introduced to produce more reproducable floating point output for regression tests. The rationale is, that an exact output value is much more likely to be 1/8 than 0.124997. If we round to two digits though, 1/8 becomes unreliably either .12 or .13 due to machine accuracy. On the other hand, if we add a something above machine accuracy first, we will always get .13.

It is safe to leave this value equal to zero. For regression tests, the function test_mode() sets it to a reasonable value.

The offset is relative to the magnitude of the number.

Definition at line 547 of file logstream.h.

Referenced by operator<<().

Flag for printing thread id.

Definition at line 552 of file logstream.h.

The value times() returned on initialization.

Definition at line 558 of file logstream.h.

struct tms LogStream::reference_tms [private]

The tms structure times() filled on initialization.

Definition at line 564 of file logstream.h.

std::streambuf* LogStream::old_cerr [private]

Original buffer of std::cerr. We store the address of that buffer when log_cerr is called, and reset it to this value if log_cerr is called a second time, or when the destructor of this class is run.

Definition at line 576 of file logstream.h.

We generate a stringstream for every process that sends log messages.

Definition at line 611 of file logstream.h.


The documentation for this class was generated from the following file:
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines

deal.II documentation generated on Fri Feb 3 2012 06:04:09 by doxygen 1.7.2