#include <deal.II/base/logstream.h>

Inheritance diagram for LogStream:

Classes
class	Prefix

Public Member Functions
	LogStream ()

	~LogStream ()

void	attach (std::ostream &o, const bool print_job_id=true)

void	detach ()

void	test_mode (const bool on=true, const double double_threshold=1.e-10, const float float_threshold=1.e-7f, const double offset=1.e-7)

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)

LogStream &	operator<< (const double t)

LogStream &	operator<< (const float t)

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

std::size_t	memory_consumption () const

Public Member Functions inherited from Subscriptor
	Subscriptor ()

	Subscriptor (const Subscriptor &)

	Subscriptor (Subscriptor &&)

virtual	~Subscriptor ()

Subscriptor &	operator= (const Subscriptor &)

Subscriptor &	operator= (Subscriptor &&)

void	subscribe (const char *identifier=0) const

void	unsubscribe (const char *identifier=0) const

unsigned int	n_subscriptions () const

void	list_subscribers () const

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 >
LogStream &	operator<< (LogStream &log, const T &t)

Additional Inherited Members
Static Public Member Functions inherited from Subscriptor
static ::ExceptionBase &	ExcInUse (int arg1, char *arg2, std::string &arg3)

static ::ExceptionBase &	ExcNoSubscriber (char arg1, char arg2)

Detailed Description

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

a push and pop mechanism for prefixes, and
the possibility of distributing information to files and the console.

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

deallog.depth_console(n): restrict output on screen to outer loops.
deallog.attach(std::ostream): write logging information into a file.
deallog.depth_file(n): restrict output to file to outer loops.

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.

Write 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:

Every write to a Logstream with operator << (or with one of the special member functions) is buffered in a thread-local storage.
An std::flush or std::endl will trigger a writeout to the console and (if attached) to the file stream. This writeout is sequentialized so that output from concurrent threads don't interleave.
On a new thread, invoking a writeout, as well as a call to push or pop will copy the current prefix of the "blessed" thread that created the LogStream instance to a thread-local storage. After that prefixes are thread-local.

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:

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.
For float numbers holds the same, but with a typically larger float_threshold.
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::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::~LogStream ( )

Destructor.

Definition at line 73 of file logstream.cc.

Member Function Documentation

◆ attach()

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 224 of file logstream.cc.

◆ detach()

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 235 of file logstream.cc.

◆ test_mode()

void LogStream::test_mode	(	const bool	on = `true`,
		const double	double_threshold = `1.e-10`,
		const float	float_threshold = `1.e-7f`,
		const double	offset = `1.e-7`
	)

Setup the logstream for regression test mode.

This sets the parameters double_threshold, float_threshold, and offset to nonzero values. The default values being used have been determined experimentally.

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

Definition at line 113 of file logstream.cc.

◆ get_console()

std::ostream & LogStream::get_console ( )

Gives the default stream (std_out).

Definition at line 258 of file logstream.cc.

◆ get_file_stream()

std::ostream & LogStream::get_file_stream ( )

Gives the file stream.

Definition at line 265 of file logstream.cc.

◆ has_file()

bool LogStream::has_file ( ) const

Returns: true, if file stream has already been attached.

Definition at line 275 of file logstream.cc.

◆ log_cerr()

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 242 of file logstream.cc.

◆ get_prefix()

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

Return the prefix string.

Definition at line 282 of file logstream.cc.

◆ push()

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 294 of file logstream.cc.

◆ pop()

void LogStream::pop ( )

Remove the last prefix added with push().

Definition at line 306 of file logstream.cc.

◆ depth_console()

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 335 of file logstream.cc.

◆ depth_file()

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 345 of file logstream.cc.

◆ log_execution_time()

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 371 of file logstream.cc.

◆ log_time_differences()

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 381 of file logstream.cc.

◆ timestamp()

void LogStream::timestamp ( )

Write detailed timing information.

Definition at line 490 of file logstream.cc.

◆ log_thread_id()

bool LogStream::log_thread_id ( const bool flag )

Log the thread id.

Definition at line 391 of file logstream.cc.

◆ threshold_double()

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 355 of file logstream.cc.

◆ threshold_float()

void LogStream::threshold_float ( const float t )

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

Definition at line 363 of file logstream.cc.

◆ precision()

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 321 of file logstream.cc.

◆ width()

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 328 of file logstream.cc.

◆ flags()

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 314 of file logstream.cc.

◆ operator<<() [1/3]

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

◆ operator<<() [2/3]

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

◆ operator<<() [3/3]

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 135 of file logstream.cc.

◆ memory_consumption()

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 514 of file logstream.cc.

◆ get_prefixes()

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 400 of file logstream.cc.

◆ print_line_head()

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 433 of file logstream.cc.

◆ get_stream()

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

Friends And Related Function Documentation

◆ operator<<

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

Member Data Documentation

◆ prefixes

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

◆ std_out

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

◆ file

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

◆ std_depth

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

◆ file_depth

unsigned int LogStream::file_depth

private

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

Definition at line 448 of file logstream.h.

◆ print_utime

bool LogStream::print_utime

private

Flag for printing execution time.

Definition at line 453 of file logstream.h.

◆ diff_utime

bool LogStream::diff_utime

private

Flag for printing time differences.

Definition at line 458 of file logstream.h.

◆ last_time

double LogStream::last_time

private

Time of last output line.

Definition at line 463 of file logstream.h.

◆ double_threshold

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

◆ float_threshold

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

◆ offset

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

◆ print_thread_id

bool LogStream::print_thread_id

private

Flag for printing thread id.

Definition at line 499 of file logstream.h.

◆ reference_time_val

double LogStream::reference_time_val

private

The value times() returned on initialization.

Definition at line 504 of file logstream.h.

◆ reference_tms

struct tms LogStream::reference_tms

private

The tms structure times() filled on initialization.

Definition at line 509 of file logstream.h.

◆ old_cerr

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

◆ at_newline

bool LogStream::at_newline

private

A flag indicating whether output is currently at a new line

Definition at line 521 of file logstream.h.

◆ outstreams

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

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

deal.II/base/logstream.h
source/base/logstream.cc

Classes

Public Member Functions

Private Member Functions

Private Attributes

Friends

Additional Inherited Members

Detailed Description

LogStream and thread safety

LogStream and reproducible regression test output

Constructor & Destructor Documentation

◆ LogStream()

◆ ~LogStream()

Member Function Documentation

◆ attach()

◆ detach()

◆ test_mode()

◆ get_console()

◆ get_file_stream()

◆ has_file()

◆ log_cerr()

◆ get_prefix()

◆ push()

◆ pop()

◆ depth_console()

◆ depth_file()

◆ log_execution_time()

◆ log_time_differences()

◆ timestamp()

◆ log_thread_id()

◆ threshold_double()

◆ threshold_float()

◆ precision()

◆ width()

◆ flags()

◆ operator<<() [1/3]

◆ operator<<() [2/3]

◆ operator<<() [3/3]

◆ memory_consumption()

◆ get_prefixes()

◆ print_line_head()

◆ get_stream()

Friends And Related Function Documentation

◆ operator<<

Member Data Documentation

◆ prefixes

◆ std_out

◆ file

◆ std_depth

◆ file_depth

◆ print_utime

◆ diff_utime

◆ last_time

◆ double_threshold

◆ float_threshold

◆ offset

◆ print_thread_id

◆ reference_time_val

◆ reference_tms

◆ old_cerr

◆ at_newline

◆ outstreams