![]() |
Reference documentation for deal.II version 8.1.0
|
#include <logstream.h>
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) |
LogStream & | operator<< (const double t) |
LogStream & | operator<< (const float t) |
LogStream & | operator<< (std::ostream &(*p)(std::ostream &)) |
std::size_t | memory_consumption () const |
DeclException0 (ExcNoFileStreamGiven) | |
![]() | |
Subscriptor () | |
Subscriptor (const Subscriptor &) | |
virtual | ~Subscriptor () |
Subscriptor & | operator= (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 > | |
LogStream & | operator<< (LogStream &log, const T &t) |
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:
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.
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.
In the vicinity of concurrent threads, LogStream behaves in the following manner:
<<
(or with one of the special member functions) is buffered in a thread-local storage. 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. 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:
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.
Definition at line 117 of file logstream.h.
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.
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 |
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 | ) |
void LogStream::pop | ( | ) |
Remove the last prefix added with push().
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.
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.
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.
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.
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/
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.
|
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.
|
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).
|
private |
Print head of line. This prints optional time information and the contents of the prefix stack.
|
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.
Output a constant something through LogStream:
Definition at line 570 of file logstream.h.
|
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.
|
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.
|
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.
|
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.
|
private |
Same for the maximum depth of prefixes for output to a file.
Definition at line 459 of file logstream.h.
|
private |
Flag for printing execution time.
Definition at line 464 of file logstream.h.
|
private |
Flag for printing time differences.
Definition at line 469 of file logstream.h.
|
private |
Time of last output line.
Definition at line 474 of file logstream.h.
|
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.
|
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.
|
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.
|
private |
Flag for printing thread id.
Definition at line 510 of file logstream.h.
|
private |
The value times() returned on initialization.
Definition at line 515 of file logstream.h.
|
private |
The tms structure times() filled on initialization.
Definition at line 520 of file logstream.h.
|
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.
|
private |
A flag indicating whether output is currently at a new line
Definition at line 533 of file logstream.h.
|
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.