linbox  1
Public Member Functions | Public Attributes
Commentator Class Reference

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>

List of all members.

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)
MessageClassregisterMessageClass (const char *msg_class, std::ostream &stream, unsigned long max_depth=1, unsigned long max_level=2)
MessageClasscloneMessageClass (const char *new_msg_class, const char *msg_class)
MessageClasscloneMessageClass (const char *new_msg_class, const char *msg_class, std::ostream &stream)
MessageClassgetMessageClass (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)

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

Message level Some default settings to use for the message level

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


Constructor & Destructor Documentation

Default constructor Constructs a commentator with default settings

~Commentator ( ) [virtual]

Default destructor


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)
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:
iterNumber of the iteration
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)
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.

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.
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
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.

Returns:
ActivityState object

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.

Parameters:
depthMaximum 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

Parameters:
levelMaximum 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.

Parameters:
msg_className of message class
streamStream to which to send data of this type
max_depthDefault maximum recursion depth at which to print messages of this class (default 1)
max_levelDefault 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
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_className of the new class
msg_className of class to clone
Returns:
A reference to the new message class object
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_className of the new class
msg_className of class to clone
streamNew stream to which to direct output
Returns:
A reference to the new message class object
MessageClass & getMessageClass ( const char *  msg_class)

Retrieve a message class by name

Parameters:
msg_className of message class
Returns:
Reference to message class object
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:
depthDepth up to which directive is valid
levelDetail level up to which directive is valid
fnFully 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

Parameters:
formatOutput format
show_timingShow the CPU time for each toplevel activity
show_progressShow a counter of the progress as each activity progresses
show_est_timeShow 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

Parameters:
depthActivity depth
levelMessage level
msg_classType of message
fnFully qualified function name (0 if not applicable)
Returns:
true if the message with the given characteristics will be printed as things are currently configured
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:
levelMessage level
msg_classType of message
fnFully qualified function name (0 if not applicable)
Returns:
true if the message with the given characteristics will be printed as things are currently configured
bool isNullStream ( const std::ostream &  str) [inline]

Determine whether the stream given is the null stream

Parameters:
streamStream to check
Returns:
true if stream is the null stream; false otherwise
void setBriefReportStream ( std::ostream &  stream)

Set output stream for brief report

Parameters:
streamOutput stream
void setReportStream ( std::ostream &  stream)

Set output stream for all reports other than the brief report

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

Set the output stream for a given message class

Parameters:
msg_classMessage class
streamOutput stream
void setDefaultReportFile ( const char *  filename)

Set default report file

Parameters:
nameof file
void start ( const char *  id,
const char *  msg,
long  msglevel,
const char *  msgclass 
) [inline]

Start an activity

Parameters:
idString identifier of activity
msgMessage to print
msglevelLevel of message
msgclassClass of message
void stop ( const char *  msg,
long  msglevel,
const char *  msgclass,
long  time_type 
) [inline]

Stop an activity

Parameters:
msgMessage to print
msglevelLevel of message
msgclassClass of message
time_typeType of timing to use
void progress ( const char *  msg,
long  msglevel,
long  k,
long  n 
) [inline]

Report progress

Parameters:
msgMessage to print
msglevelLevel of message
kNumber of steps completed
nTotal number of steps in operation
void report ( const char *  msg,
long  msglevel,
const char *  msgclass 
) [inline]

General reporting

Parameters:
msgMessage to print
msglevelLevel of message
msgclassClass of message
bool printed ( long  msglevel,
const char *  msgclass 
) [inline]

Test whether message is printed

Parameters:
msglevelLevel of message
msgclassClass of message

Member Data Documentation

std::ostream cnull

Use this stream to disable a message class entirely


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