Commentator Class Reference

Give information to user during runtime. More...

#include <commentator.h>

Data Structures
struct	Activity
struct	C_str_Less
struct	StepsAndTime

Public Member Functions
	Commentator ()
	Commentator (std::ostream &)
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)

Reporting facilities.
enum	MessageLevel { LEVEL_ALWAYS = 0 , LEVEL_IMPORTANT = 1 , LEVEL_NORMAL = 2 , LEVEL_UNIMPORTANT = 3 }
void	start (const char *description, const char *fn=(const char *) 0, unsigned long len=0)
	Start an activity.
void	start (std::string 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="done", const char *long_msg=(const char *) 0, const char *fn=(const char *) 0)
	Stop an activity.
void	progress (long k=-1, long len=-1)
	Report progress in the current activity.
std::ostream &	report (long level=LEVEL_IMPORTANT, const char *msg_class="Internal description")
	Basic reporting.
void	indent (std::ostream &stream) const

Configuration
enum	OutputFormat { OUTPUT_CONSOLE , OUTPUT_PIPE }
enum	EstimationMethod { BEST_ESTIMATE , POLY_ESTIMATE , EXPO_ESTIMATE }
enum	TimingDelay { SHORT_TIMING , LONG_TIMING }
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)

Legacy commentator interface
These routines provide compatibility with the old commentator interface. They are deprecated. Deprecated
typedef std::deque< StepsAndTime >	Estimator
std::ofstream	cnull
std::stack< Activity * >	_activities
std::map< const char *, MessageClass *, C_str_Less >	_messageClasses
EstimationMethod	_estimationMethod
OutputFormat	_format
bool	_show_timing
bool	_show_progress
bool	_show_est_time
unsigned int	_last_line_len
std::ofstream	_report
std::string	_iteration_str
void	start (const char *id, const char *msg, long msglevel, const char *msgclass)
void	start (std::string id, const char *msg, long msglevel, const char *msgclass)
void	stop (const char *msg, long, const char *, long)
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)
virtual void	printActivityReport (Activity &activity)
virtual void	updateActivityReport (Activity &activity)
virtual void	finishActivityReport (Activity &activity, const char *msg)

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 Typedef Documentation

Estimator

typedef std::deque<StepsAndTime> Estimator

protected

Use this stream to disable a message class entirely.

Member Enumeration Documentation

MessageLevel

enum MessageLevel

Message level. Some default settings to use for the message level

Enumerator
LEVEL_ALWAYS
LEVEL_IMPORTANT
LEVEL_NORMAL
LEVEL_UNIMPORTANT

OutputFormat

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

Enumerator
OUTPUT_CONSOLE
OUTPUT_PIPE

EstimationMethod

enum EstimationMethod

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

Enumerator
BEST_ESTIMATE
POLY_ESTIMATE
EXPO_ESTIMATE

TimingDelay

enum TimingDelay

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

Enumerator
SHORT_TIMING
LONG_TIMING

Constructor & Destructor Documentation

Commentator() [1/2]

Commentator

(

)

Default constructor. Constructs a commentator with default settings

Commentator() [2/2]

Commentator

(

std::ostream &

out

)

~Commentator()

~Commentator ( )

virtual

Default destructor.

Member Function Documentation

start() [1/4]

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)

start() [2/4]

void start	(	std::string	description,
		const char *	fn = (const char *) 0,
		unsigned long	len = 0 )

Message level. Some default settings to use for the message level

startIteration()

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

Parameters

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)

stop() [1/2]

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.

progress() [1/2]

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() [1/2]

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

indent()

void indent

(

std::ostream &

stream

)

const

Indent to the correct column on the given string.

saveActivityState()

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.

Returns

ActivityState object

restoreActivityState()

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.

setMaxDepth()

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.

Parameters

depth

Maximum depth at which to print messages; set to -1 to print messages at any depth and 0 to disable entirely

setMaxDetailLevel()

void setMaxDetailLevel

(

long

level

)

Set maximum detail level. Sets the maximum detail level at which to print messages

Parameters

level

Maximum detail level at which to print messages; set to -1 to print messages at all levels and 0 to disable entirely

registerMessageClass()

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.

Parameters

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)

Returns

A reference to the new message class object

cloneMessageClass() [1/2]

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.

Parameters

new_msg_class	Name of the new class
msg_class	Name of class to clone

Returns

A reference to the new message class object

cloneMessageClass() [2/2]

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.

Parameters

new_msg_class	Name of the new class
msg_class	Name of class to clone
stream	New stream to which to direct output

Returns

A reference to the new message class object

getMessageClass()

MessageClass & getMessageClass

(

const char *

msg_class

)

Retrieve a message class by name.

Parameters

msg_class

Name of message class

Returns

Reference to message class object

setPrintParameters()

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.

Parameters

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

setBriefReportParameters()

void setBriefReportParameters	(	OutputFormat	format,
		bool	show_timing,
		bool	show_progress,
		bool	show_est_time )

Set parameters for the brief report.

Parameters

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

isPrinted() [1/2]

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.

Parameters

depth	Activity depth
level	Message level
msg_class	Type of message
fn	Fully qualified function name (0 if not applicable)

Returns

true if the message with the given characteristics will be printed as things are currently configured

isPrinted() [2/2]

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.

Parameters

level	Message level
msg_class	Type of message
fn	Fully qualified function name (0 if not applicable)

Returns

true if the message with the given characteristics will be printed as things are currently configured

isNullStream()

bool isNullStream ( const std::ostream & str )

inline

Determine whether the stream given is the null stream.

Parameters

str	Stream to check

Returns

true if stream is the null stream; false otherwise

setBriefReportStream()

void setBriefReportStream

(

std::ostream &

stream

)

Set output stream for brief report.

Parameters

stream

Output stream

setReportStream()

void setReportStream

(

std::ostream &

stream

)

Set output stream for all reports other than the brief. report

Parameters

stream

Output stream

setMessageClassStream()

void setMessageClassStream	(	const char *	msg_class,
		std::ostream &	stream )

Set the output stream for a given message class.

Parameters

msg_class	Message class
stream	Output stream

setDefaultReportFile()

void setDefaultReportFile

(

const char *

filename

)

Set default report file.

Parameters

filename

of file

start() [3/4]

void start ( const char * id, const char * msg, long msglevel, const char * msgclass )

inline

Start an activity.

Parameters

id	String identifier of activity
msg	Message to print
msglevel	Level of message
msgclass	Class of message

start() [4/4]

void start ( std::string id, const char * msg, long msglevel, const char * msgclass )

inline

Use this stream to disable a message class entirely.

stop() [2/2]

void stop ( const char * msg, long , const char * , long  )

inline

Stop an activity.

Parameters

msg	Message to print

progress() [2/2]

void progress ( const char * msg, long msglevel, long k, long n )

inline

Report progress.

Parameters

msg	Message to print
msglevel	Level of message
k	Number of steps completed
n	Total number of steps in operation

report() [2/2]

void report ( const char * msg, long msglevel, const char * msgclass )

inline

General reporting.

Parameters

msg	Message to print
msglevel	Level of message
msgclass	Class of message

printed()

bool printed ( long msglevel, const char * msgclass )

inline

Test whether message is printed.

Parameters

msglevel	Level of message
msgclass	Class of message

printActivityReport()

void printActivityReport ( Activity & activity )

protectedvirtual

Use this stream to disable a message class entirely.

updateActivityReport()

void updateActivityReport ( Activity & activity )

protectedvirtual

Use this stream to disable a message class entirely.

finishActivityReport()

void finishActivityReport ( Activity & activity, const char * msg )

protectedvirtual

Use this stream to disable a message class entirely.

Field Documentation

cnull

std::ofstream cnull

Use this stream to disable a message class entirely.

_activities

std::stack<Activity *> _activities

protected

Use this stream to disable a message class entirely.

_messageClasses

std::map<const char *, MessageClass *, C_str_Less> _messageClasses

protected

Use this stream to disable a message class entirely.

_estimationMethod

EstimationMethod _estimationMethod

protected

Use this stream to disable a message class entirely.

_format

OutputFormat _format

protected

Use this stream to disable a message class entirely.

_show_timing

bool _show_timing

protected

Use this stream to disable a message class entirely.

_show_progress

bool _show_progress

protected

Use this stream to disable a message class entirely.

_show_est_time

bool _show_est_time

protected

Use this stream to disable a message class entirely.

_last_line_len

unsigned int _last_line_len

protected

Use this stream to disable a message class entirely.

_report

std::ofstream _report

protected

Use this stream to disable a message class entirely.

_iteration_str

std::string _iteration_str

protected

Use this stream to disable a message class entirely.

---

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

• commentator.h
• commentator.inl