linbox
Public Member Functions
Commentator Class Reference

Give information to user during runtime. More...

#include <commentator.h>

Public Member Functions

void start (const char *description, const char *fn=(const char *) 0, unsigned long len=0)
 Start an activity. More...
 
void stop (const char *msg="done", const char *long_msg=(const char *) 0, const char *fn=(const char *) 0)
 Stop an activity. More...
 
void progress (long k=-1, long len=-1)
 Report progress in the current activity. More...
 
std::ostream & report (long level=LEVEL_IMPORTANT, const char *msg_class="Internal description")
 Basic reporting. More...
 

Detailed Description

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.

Member Function Documentation

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.

Parameters
descriptionA human-readable text description of the activity
fnThe fully-qualified name of the function. Use 0 to use the same function as the surrounding activity (default 0)
lenNumber of items involved in this activity. Used for progress reporting; use 0 if this is not applicable to the situation in question. (default 0)
Examples:
examples/charpoly.C, and examples/dot-product.C.
void stop ( const char *  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.

Parameters
msgA short (one word) message describing the termination, e.g. "passed", "FAILED", "ok", etc.
long_msgA longer message describing the nature of the termination. May be 0, in which case msg is used.
fnName 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.
Examples:
examples/charpoly.C, and examples/dot-product.C.
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.

Parameters
kNumber of steps completed; use -1 to increment the current counter
lenTotal 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

Parameters
levelLevel of detail of the message
msg_classType of message
Returns
A reference to the stream to which to output data
Examples:
examples/graph-charpoly.C.

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