Reference documentation for deal.II version 8.1.0
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Modules Pages
Classes | Public Member Functions | Private Member Functions | Private Attributes | Friends | List of all members
LogStream Class Reference

#include <logstream.h>

Inheritance diagram for LogStream:
[legend]

Classes

class  Prefix
 

Public Member Functions

 LogStream ()
 
 ~LogStream ()
 
void attach (std::ostream &o, const bool print_job_id=true)
 
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)
 
std::streamsize precision (const std::streamsize prec)
 
std::streamsize width (const std::streamsize wide)
 
std::ios::fmtflags flags (const std::ios::fmtflags f)
 
LogStreamoperator<< (const double t)
 
LogStreamoperator<< (const float t)
 
LogStreamoperator<< (std::ostream &(*p)(std::ostream &))
 
std::size_t memory_consumption () const
 
 DeclException0 (ExcNoFileStreamGiven)
 
- Public Member Functions inherited from Subscriptor
 Subscriptor ()
 
 Subscriptor (const Subscriptor &)
 
virtual ~Subscriptor ()
 
Subscriptoroperator= (const Subscriptor &)
 
void subscribe (const char *identifier=0) const
 
void unsubscribe (const char *identifier=0) const
 
unsigned int n_subscriptions () const
 
void list_subscribers () const
 
 DeclException3 (ExcInUse, int, char *, std::string &,<< "Object of class "<< arg2<< " is still used by "<< arg1<< " other objects.\n"<< "(Additional information: "<< arg3<< ")\n"<< "Note the entry in the Frequently Asked Questions of "<< "deal.II (linked to from http://www.dealii.org/) for "<< "more information on what this error means.")
 
 DeclException2 (ExcNoSubscriber, char *, char *,<< "No subscriber with identifier \""<< arg2<< "\" did subscribe to this object of class "<< arg1)
 
template<class Archive >
void serialize (Archive &ar, const unsigned int version)
 

Private Member Functions

std::stack< std::string > & get_prefixes () const
 
void print_line_head ()
 
std::ostringstream & get_stream ()
 

Private Attributes

Threads::ThreadLocalStorage
< 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
 
bool at_newline
 
Threads::ThreadLocalStorage
< std_cxx1x::shared_ptr
< std::ostringstream > > 
outstreams
 

Friends

template<typename T >
LogStreamoperator<< (LogStream &log, const T &t)
 

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 setup steps are:

Before entering a new phase of your program, e.g. a new loop, a new prefix can be set via LogStream::Prefix p("loopname");. The destructor of the prefix will pop the prefix text from the stack.

Writes via the << operator, deallog << "This is a log notice"; will be buffered thread locally until a std::flush or std::endl is encountered, which will trigger a writeout to the console and, if set up, the log file.

LogStream and thread safety

In the vicinity of concurrent threads, LogStream behaves in the following manner:

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 117 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,
const bool  print_job_id = true 
)

Enable output to a second stream o.

The optional argument print_job_id specifies whether

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)

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

A simpler way to add a prefix (without the manual need to add the corresponding pop()) is to use the Prefix class.

void LogStream::pop ( )

Remove the last prefix added with push().

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.

std::streamsize LogStream::precision ( const std::streamsize  prec)

set the precision for the underlying stream and returns the previous stream precision. This fuction mimics http://www.cplusplus.com/reference/ios/ios_base/precision/

std::streamsize LogStream::width ( const std::streamsize  wide)

set the width for the underlying stream and returns the previous stream width. This fuction mimics http://www.cplusplus.com/reference/ios/ios_base/width/

std::ios::fmtflags LogStream::flags ( const std::ios::fmtflags  f)

set the flags for the underlying stream and returns the previous stream flags. This fuction mimics http://www.cplusplus.com/reference/ios/ios_base/flags/

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 605 of file logstream.h.

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 627 of file logstream.h.

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.

LogStream::DeclException0 ( ExcNoFileStreamGiven  )

Exception.

std::stack<std::string>& LogStream::get_prefixes ( ) const
private

Internal wrapper around thread-local prefixes. This private function will return the correct internal prefix stack. More important, a new thread-local stack will be copied from the current stack of the "blessed" thread that created this LogStream instance (usually, in the case of deallog, the "main" thread).

void LogStream::print_line_head ( )
private

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

std::ostringstream & LogStream::get_stream ( )
inlineprivate

Internal wrapper around "thread local" outstreams. This private function will return the correct internal ostringstream buffer for operater<<.

Definition at line 580 of file logstream.h.

Friends And Related Function Documentation

template<typename T >
LogStream& operator<< ( LogStream log,
const T &  t 
)
friend

Output a constant something through LogStream:

Note
We declare this operator as a non-member function so that it is possible to overload it with more specialized templated versions under C++11 overload resolution rules

Definition at line 570 of file logstream.h.

Member Data Documentation

Threads::ThreadLocalStorage<std::stack<std::string> > LogStream::prefixes
mutableprivate

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

Definition at line 431 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 438 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 446 of file logstream.h.

unsigned int LogStream::std_depth
private

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 454 of file logstream.h.

unsigned int LogStream::file_depth
private

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

Definition at line 459 of file logstream.h.

bool LogStream::print_utime
private

Flag for printing execution time.

Definition at line 464 of file logstream.h.

bool LogStream::diff_utime
private

Flag for printing time differences.

Definition at line 469 of file logstream.h.

double LogStream::last_time
private

Time of last output line.

Definition at line 474 of file logstream.h.

double LogStream::double_threshold
private

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

Definition at line 480 of file logstream.h.

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 486 of file logstream.h.

double LogStream::offset
private

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 reproducible 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 505 of file logstream.h.

bool LogStream::print_thread_id
private

Flag for printing thread id.

Definition at line 510 of file logstream.h.

double LogStream::reference_time_val
private

The value times() returned on initialization.

Definition at line 515 of file logstream.h.

struct tms LogStream::reference_tms
private

The tms structure times() filled on initialization.

Definition at line 520 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 528 of file logstream.h.

bool LogStream::at_newline
private

A flag indicating whether output is currently at a new line

Definition at line 533 of file logstream.h.

Threads::ThreadLocalStorage<std_cxx1x::shared_ptr<std::ostringstream> > LogStream::outstreams
private

We use tbb's thread local storage facility to generate a stringstream for every thread that sends log messages.

Definition at line 552 of file logstream.h.


The documentation for this class was generated from the following file: