linbox
1
|
give information to user during runtimeThis object is used for reporting information about a computation to the user. Such information includes errors and warnings, descriptions of internal progress, performance measurements, and timing estimates. It also includes facilities for controlling the type and amount of information displayed. More...
#include <commentator.h>
Public Member Functions | |
Commentator () | |
virtual | ~Commentator () |
Activity stack restoration | |
The methods below facilitate restoring the activity stack after an exception has been thrown. If user code wishes to catch an exception, it should invoke the method saveActivityState before the try block, storing the result in an ActivityState object. Then it may invoke restoreActivityState, passing the ActivityState object, in each of the catch blocks. | |
ActivityState | saveActivityState () const |
void | restoreActivityState (ActivityState state) |
Legacy commentator interface | |
These routines provide compatibility with the old commentator interface. They are deprecated. | |
void | start (const char *id, const char *msg, long msglevel, const char *msgclass) |
void | stop (const char *msg, long msglevel, const char *msgclass, long time_type) |
void | progress (const char *msg, long msglevel, long k, long n) |
void | report (const char *msg, long msglevel, const char *msgclass) |
bool | printed (long msglevel, const char *msgclass) |
Public Attributes | |
std::ostream | cnull |
Reporting facilities | |
enum | MessageLevel |
void | start (const char *description, const char *fn=(const char *) 0, unsigned long len=0) |
void | startIteration (unsigned int iter, unsigned long len=0) |
void | stop (const char *msg=MSG_DONE, const char *long_msg=(const char *) 0, const char *fn=(const char *) 0) |
void | progress (long k=-1, long len=-1) |
std::ostream & | report (long level=LEVEL_IMPORTANT, const char *msg_class=INTERNAL_DESCRIPTION) |
void | indent (std::ostream &stream) const |
Configuration | |
enum | OutputFormat |
enum | EstimationMethod |
enum | TimingDelay |
void | setMaxDepth (long depth) |
void | setMaxDetailLevel (long level) |
MessageClass & | registerMessageClass (const char *msg_class, std::ostream &stream, unsigned long max_depth=1, unsigned long max_level=2) |
MessageClass & | cloneMessageClass (const char *new_msg_class, const char *msg_class) |
MessageClass & | cloneMessageClass (const char *new_msg_class, const char *msg_class, std::ostream &stream) |
MessageClass & | getMessageClass (const char *msg_class) |
void | setPrintParameters (unsigned long depth, unsigned long level, const char *fn=(const char *) 0) |
void | setBriefReportParameters (OutputFormat format, bool show_timing, bool show_progress, bool show_est_time) |
bool | isPrinted (unsigned long depth, unsigned long level, const char *msg_class, const char *fn=(const char *) 0) |
bool | isPrinted (unsigned long level, const char *msg_class, const char *fn=(const char *) 0) |
bool | isNullStream (const std::ostream &str) |
void | setBriefReportStream (std::ostream &stream) |
void | setReportStream (std::ostream &stream) |
void | setMessageClassStream (const char *msg_class, std::ostream &stream) |
void | setDefaultReportFile (const char *filename) |
give information to user during runtime
This object is used for reporting information about a computation to the user. Such information includes errors and warnings, descriptions of internal progress, performance measurements, and timing estimates. It also includes facilities for controlling the type and amount of information displayed.
* Typical usage follows the following pattern:
void myFunction () { commentator.start ("Doing important work", "myFunction", 100); for (int i = 0; i < 100; i++) { ... commentator.progress (); } commentator.stop (MSG_DONE, "Task completed successfully"); }
In the above example, the call to commentator.start () informs the commentator that some new activity has begun. This may be invoked recursively, an the commentator keeps track of nested activities. The user may elect to disable the reporting of any activities below a certain depth of nesting. The call to commentator.stop () informs the commentator that the activity started above is finished.
The call to commentator.progress () indicates that one step of the activity is complete. The commentator may then output data to the console to that effect. This allows the easy implementation of progress bars and other reporting tools.
In addition, commentator.report () allows reporting general messages, such as warnings, errors, and descriptions of internal progress.
By default, there are two reports: a brief report that outputs to cout, and a detailed report that outputs to a file that is specified. If no file is specified, the detailed report is thrown out. The brief report is intended either for human consumption or to be piped to some other process. Therefore, there are two output formats for that report. One can further customize the report style by inheriting the commentator object.
The commentator allows very precise control over what gets printed. See the Configuration section below.
enum MessageLevel |
Message level Some default settings to use for the message level
enum OutputFormat |
Output format OUTPUT_CONSOLE - output human-readable and tailor-made for the console OUTPUT_PIPE - output made for piping into other processes
This affects only the brief report
Commentator | ( | ) |
Default constructor Constructs a commentator with default settings
~Commentator | ( | ) | [virtual] |
Default destructor
void start | ( | const char * | description, |
const char * | fn = (const char *) 0 , |
||
unsigned long | len = 0 |
||
) |
Start an activity Inform the commentator that some new activity has begun. This is typically called at the beginning of a library function.
description | A human-readable text description of the activity |
fn | The fully-qualified name of the function. Use 0 to use the same function as the surrounding activity (default 0) |
len | Number of items involved in this activity. Used for progress reporting; use 0 if this is not applicable to the situation in question. (default 0) |
void startIteration | ( | unsigned int | iter, |
unsigned long | len = 0 |
||
) |
Start a new iteration This is a convenience function to indicate that an iteration has started
iter | Number of the iteration |
len | Number of items involved in this activity. Used for progress reporting; use 0 if this is not applicable to the situation in question. (default 0) |
void stop | ( | const char * | msg = MSG_DONE , |
const char * | long_msg = (const char *) 0 , |
||
const char * | fn = (const char *) 0 |
||
) |
Stop an activity Inform the commentator that the current activity has finished.
msg | A short (one word) message describing the termination, e.g. "passed", "FAILED", "ok", etc. |
long_msg | A longer message describing the nature of the termination. May be 0, in which case msg is used. |
fn | Name of the function whose activity is complete. This is intended for checking to make sure that each call to start () is matched with a call to stop (). It is optional, and has no other effect. |
void progress | ( | long | k = -1 , |
long | len = -1 |
||
) |
Report progress in the current activity Inform the commentator that k steps of the current activity have been completed.
k | Number of steps completed; use -1 to increment the current counter |
len | Total length of the operation; use -1 to use the existing length. This allows updating of inexact estimates of the number of steps. |
std::ostream & report | ( | long | level = LEVEL_IMPORTANT , |
const char * | msg_class = INTERNAL_DESCRIPTION |
||
) |
Basic reporting Send some report string to the commentator
level | Level of detail of the message |
msg_class | Type of message |
void indent | ( | std::ostream & | stream | ) | const |
Indent to the correct column on the given string
ActivityState saveActivityState | ( | ) | const [inline] |
Save activity state
Saves a copy of the activity state and returns it to the caller. The caller need only pass this object back to restoreActivityState} to return the commentator's activity stack to the state it was when saveActivityState was called.
void restoreActivityState | ( | ActivityState | state | ) |
Restore activity state
Restores the activity state to the point it was when the given ActivityState object was passed. Note that this function assumes that the commentator is currently in a more deeply-nested configuration than when the object was created; if it is not, the method will give up.
void setMaxDepth | ( | long | depth | ) |
Set maximum message depth Sets the maximum activity depth, as defined by Commentator::start and Commentator::stop, at which messages of all classes will be printed.
depth | Maximum depth at which to print messages; set to -1 to print messages at any depth and 0 to disable entirely |
void setMaxDetailLevel | ( | long | level | ) |
Set maximum detail level Sets the maximum detail level at which to print messages
level | Maximum detail level at which to print messages; set to -1 to print messages at all levels and 0 to disable entirely |
MessageClass & registerMessageClass | ( | const char * | msg_class, |
std::ostream & | stream, | ||
unsigned long | max_depth = 1 , |
||
unsigned long | max_level = 2 |
||
) |
Register a new message class Register some new message class with the commentator.
msg_class | Name of message class |
stream | Stream to which to send data of this type |
max_depth | Default maximum recursion depth at which to print messages of this class (default 1) |
max_level | Default maximum detail level at which to print messages of this class (default 2, or LEVEL_IMPORTANT) |
MessageClass & cloneMessageClass | ( | const char * | new_msg_class, |
const char * | msg_class | ||
) |
Clone an existing message class Clone the message class to construct a new message class with the same parameters.
new_msg_class | Name of the new class |
msg_class | Name of class to clone |
MessageClass & cloneMessageClass | ( | const char * | new_msg_class, |
const char * | msg_class, | ||
std::ostream & | stream | ||
) |
Clone an existing message class, specifying a new output stream Clone the message class to construct a new message class with the same parameters.
new_msg_class | Name of the new class |
msg_class | Name of class to clone |
stream | New stream to which to direct output |
MessageClass & getMessageClass | ( | const char * | msg_class | ) |
Retrieve a message class by name
msg_class | Name of message class |
void setPrintParameters | ( | unsigned long | depth, |
unsigned long | level, | ||
const char * | fn = (const char *) 0 |
||
) |
Precise control over printing Specifies that all messages up to the given depth and the given detail level should be printed
This is similar to MessageClass::setPrintParameters but affects all message classes simultaneously.
depth | Depth up to which directive is valid |
level | Detail level up to which directive is valid |
fn | Fully qualified name of the function for which this is valid; may be 0, in which case this is valid for everything |
void setBriefReportParameters | ( | OutputFormat | format, |
bool | show_timing, | ||
bool | show_progress, | ||
bool | show_est_time | ||
) |
Set parameters for the brief report
format | Output format |
show_timing | Show the CPU time for each toplevel activity |
show_progress | Show a counter of the progress as each activity progresses |
show_est_time | Show estimated time remaining |
bool isPrinted | ( | unsigned long | depth, |
unsigned long | level, | ||
const char * | msg_class, | ||
const char * | fn = (const char *) 0 |
||
) |
Determine whether a message will be printed
depth | Activity depth |
level | Message level |
msg_class | Type of message |
fn | Fully qualified function name (0 if not applicable) |
bool isPrinted | ( | unsigned long | level, |
const char * | msg_class, | ||
const char * | fn = (const char *) 0 |
||
) | [inline] |
Determine whether a message will be printed This variant uses the current activity depth rather than specifying it explicitly.
level | Message level |
msg_class | Type of message |
fn | Fully qualified function name (0 if not applicable) |
bool isNullStream | ( | const std::ostream & | str | ) | [inline] |
Determine whether the stream given is the null stream
stream | Stream to check |
void setBriefReportStream | ( | std::ostream & | stream | ) |
Set output stream for brief report
stream | Output stream |
void setReportStream | ( | std::ostream & | stream | ) |
Set output stream for all reports other than the brief report
stream | Output stream |
void setMessageClassStream | ( | const char * | msg_class, |
std::ostream & | stream | ||
) |
Set the output stream for a given message class
msg_class | Message class |
stream | Output stream |
void setDefaultReportFile | ( | const char * | filename | ) |
Set default report file
name | of file |
void start | ( | const char * | id, |
const char * | msg, | ||
long | msglevel, | ||
const char * | msgclass | ||
) | [inline] |
Start an activity
id | String identifier of activity |
msg | Message to print |
msglevel | Level of message |
msgclass | Class of message |
void stop | ( | const char * | msg, |
long | msglevel, | ||
const char * | msgclass, | ||
long | time_type | ||
) | [inline] |
Stop an activity
msg | Message to print |
msglevel | Level of message |
msgclass | Class of message |
time_type | Type of timing to use |
void progress | ( | const char * | msg, |
long | msglevel, | ||
long | k, | ||
long | n | ||
) | [inline] |
Report progress
msg | Message to print |
msglevel | Level of message |
k | Number of steps completed |
n | Total number of steps in operation |
void report | ( | const char * | msg, |
long | msglevel, | ||
const char * | msgclass | ||
) | [inline] |
General reporting
msg | Message to print |
msglevel | Level of message |
msgclass | Class of message |
bool printed | ( | long | msglevel, |
const char * | msgclass | ||
) | [inline] |
Test whether message is printed
msglevel | Level of message |
msgclass | Class of message |
std::ostream cnull |
Use this stream to disable a message class entirely