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

start()

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

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)

Examples:

examples/charpoly.C, and examples/dot-product.C.

stop()

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

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.

Examples:

examples/charpoly.C, and examples/dot-product.C.

progress()

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

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.

report()

std::ostream & report	(	long	level = LEVEL_IMPORTANT,
		const char *	msg_class = "Internal description"
	)

Basic reporting.

Send some report string to the commentator

Parameters

level	Level of detail of the message
msg_class	Type 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:

• commentator.h
• commentator.inl