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.
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.
|
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, 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, const char *msg_class) |
void | indent (std::ostream &stream) const |
Configuration |
enum | OutputFormat |
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) |
Public Member Functions |
| Commentator () |
virtual | ~Commentator () |
|
ActivityState | saveActivityState () const |
void | restoreActivityState (ActivityState state) |
|
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 |