Reference documentation for deal.II version 8.4.1
Classes | Public Member Functions | Private Member Functions | Private Attributes | Friends | List of all members
LogStream Class Reference

#include <deal.II/base/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\n"<< "(Additional information: "<< arg3<< ")\n\n"<< "See the entry in the Frequently Asked Questions of "<< "deal.II (linked to from http://www.dealii.org/) for "<< "a lot more information on what this error means and "<< "how to fix programs in which it happens.")
 
 DeclException2 (ExcNoSubscriber, char *, char *,<< "No subscriber with identifier <"<< arg2<< "> subscribes to this object of class "<< arg1<< ". Consequently, it cannot be unsubscribed.")
 
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_cxx11::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 113 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.

Definition at line 48 of file logstream.cc.

LogStream::~LogStream ( )

Destructor.

Definition at line 72 of file logstream.cc.

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

Definition at line 220 of file logstream.cc.

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.

Definition at line 231 of file logstream.cc.

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.

Definition at line 112 of file logstream.cc.

std::ostream & LogStream::get_console ( )

Gives the default stream (std_out).

Definition at line 254 of file logstream.cc.

std::ostream & LogStream::get_file_stream ( )

Gives the file stream.

Definition at line 261 of file logstream.cc.

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

Definition at line 269 of file logstream.cc.

void LogStream::log_cerr ( )

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

Definition at line 238 of file logstream.cc.

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

Return the prefix string.

Definition at line 276 of file logstream.cc.

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.

Definition at line 288 of file logstream.cc.

void LogStream::pop ( )

Remove the last prefix added with push().

Definition at line 300 of file logstream.cc.

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

Maximum number of levels to be printed on the console. The default is 0, which will not generate any output. This function allows one to restrict console output to the highest 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. See step-3 for an example usage of this method.

The previous value of this parameter is returned.

Definition at line 329 of file logstream.cc.

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 spoil the value of a log file.

The previous value of this parameter is returned.

Definition at line 339 of file logstream.cc.

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.

Definition at line 365 of file logstream.cc.

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.

Definition at line 375 of file logstream.cc.

void LogStream::timestamp ( )

Write detailed timing information.

Definition at line 484 of file logstream.cc.

bool LogStream::log_thread_id ( const bool  flag)

Log the thread id.

Definition at line 385 of file logstream.cc.

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.

Definition at line 349 of file logstream.cc.

void LogStream::threshold_float ( const float  t)

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

Definition at line 357 of file logstream.cc.

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

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

Definition at line 315 of file logstream.cc.

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

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

Definition at line 322 of file logstream.cc.

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

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

Definition at line 308 of file logstream.cc.

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 595 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 616 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.

Definition at line 131 of file logstream.cc.

std::size_t LogStream::memory_consumption ( ) const

Return an estimate for the memory consumption, in bytes, of this object. This is not exact (but will usually be close) because calculating the memory usage of trees (e.g., std::map) is difficult.

Definition at line 508 of file logstream.cc.

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).

Definition at line 394 of file logstream.cc.

void LogStream::print_line_head ( )
private

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

Definition at line 427 of file logstream.cc.

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

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

Definition at line 570 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 560 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 423 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 430 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 438 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 446 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 451 of file logstream.h.

bool LogStream::print_utime
private

Flag for printing execution time.

Definition at line 456 of file logstream.h.

bool LogStream::diff_utime
private

Flag for printing time differences.

Definition at line 461 of file logstream.h.

double LogStream::last_time
private

Time of last output line.

Definition at line 466 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 472 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 478 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 497 of file logstream.h.

bool LogStream::print_thread_id
private

Flag for printing thread id.

Definition at line 502 of file logstream.h.

double LogStream::reference_time_val
private

The value times() returned on initialization.

Definition at line 507 of file logstream.h.

struct tms LogStream::reference_tms
private

The tms structure times() filled on initialization.

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

bool LogStream::at_newline
private

A flag indicating whether output is currently at a new line

Definition at line 524 of file logstream.h.

Threads::ThreadLocalStorage<std_cxx11::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 542 of file logstream.h.


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