<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<title>linbox: Commentator Class Reference</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="doxygen.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<!-- Generated by Doxygen 1.7.4 -->
<script type="text/javascript">
function hasClass(ele,cls) {
return ele.className.match(new RegExp('(\\s|^)'+cls+'(\\s|$)'));
}
function addClass(ele,cls) {
if (!this.hasClass(ele,cls)) ele.className += " "+cls;
}
function removeClass(ele,cls) {
if (hasClass(ele,cls)) {
var reg = new RegExp('(\\s|^)'+cls+'(\\s|$)');
ele.className=ele.className.replace(reg,' ');
}
}
function toggleVisibility(linkObj) {
var base = linkObj.getAttribute('id');
var summary = document.getElementById(base + '-summary');
var content = document.getElementById(base + '-content');
var trigger = document.getElementById(base + '-trigger');
if ( hasClass(linkObj,'closed') ) {
summary.style.display = 'none';
content.style.display = 'block';
trigger.src = 'open.png';
removeClass(linkObj,'closed');
addClass(linkObj,'opened');
} else if ( hasClass(linkObj,'opened') ) {
summary.style.display = 'block';
content.style.display = 'none';
trigger.src = 'closed.png';
removeClass(linkObj,'opened');
addClass(linkObj,'closed');
}
return false;
}
</script>
<div id="top">
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td style="padding-left: 0.5em;">
<div id="projectname">linbox</div>
</td>
</tr>
</tbody>
</table>
</div>
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main Page</span></a></li>
<li><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="modules.html"><span>Modules</span></a></li>
<li><a href="namespaces.html"><span>Namespaces</span></a></li>
<li class="current"><a href="annotated.html"><span>Data Structures</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
<li><a href="dirs.html"><span>Directories</span></a></li>
<li><a href="examples.html"><span>Examples</span></a></li>
</ul>
</div>
<div id="navrow2" class="tabs2">
<ul class="tablist">
<li><a href="annotated.html"><span>Data Structures</span></a></li>
<li><a href="hierarchy.html"><span>Class Hierarchy</span></a></li>
<li><a href="functions.html"><span>Data Fields</span></a></li>
</ul>
</div>
<div id="nav-path" class="navpath">
<ul>
<li class="navelem"><a class="el" href="namespace_lin_box.html">LinBox</a> </li>
<li class="navelem"><a class="el" href="class_lin_box_1_1_commentator.html">Commentator</a> </li>
</ul>
</div>
</div>
<div class="header">
<div class="summary">
<a href="#pub-methods">Public Member Functions</a> </div>
<div class="headertitle">
<div class="title">Commentator Class Reference<div class="ingroups"><a class="el" href="group__util.html">util</a></div></div> </div>
</div>
<div class="contents">
<!-- doxytag: class="LinBox::Commentator" -->
<p>Give information to user during runtime.
<a href="class_lin_box_1_1_commentator.html#details">More...</a></p>
<p><code>#include <commentator.h></code></p>
<table class="memberdecls">
<tr><td colspan="2"><h2><a name="pub-methods"></a>
Public Member Functions</h2></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="class_lin_box_1_1_commentator.html#a9b3772c898bc20f270af8d75ddc62090">start</a> (const char *description, const char *fn=(const char *) 0, unsigned long len=0)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Start an activity. <a href="#a9b3772c898bc20f270af8d75ddc62090"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="class_lin_box_1_1_commentator.html#a3a418a21b882e15baa44fe8bef7aca84">stop</a> (const char *msg=MSG_DONE, const char *long_msg=(const char *) 0, const char *fn=(const char *) 0)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Stop an activity. <a href="#a3a418a21b882e15baa44fe8bef7aca84"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="class_lin_box_1_1_commentator.html#a9a39a88fa3e76ae8da02c2e49518ba1b">progress</a> (long k=-1, long len=-1)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Report progress in the current activity. <a href="#a9a39a88fa3e76ae8da02c2e49518ba1b"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">std::ostream & </td><td class="memItemRight" valign="bottom"><a class="el" href="class_lin_box_1_1_commentator.html#a8dd0050b1bbb1722d2c754d6c85a4ec4">report</a> (long level=LEVEL_IMPORTANT, const char *msg_class=INTERNAL_DESCRIPTION)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Basic reporting. <a href="#a8dd0050b1bbb1722d2c754d6c85a4ec4"></a><br/></td></tr>
<tr><td colspan="2"><div class="groupHeader"></div></td></tr>
</table>
<hr/><a name="details" id="details"></a><h2>Detailed Description</h2>
<div class="textblock"><p>Give information to user during runtime. </p>
<p>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.</p>
<p>Typical usage follows the following pattern: </p>
<div class="fragment"><pre class="fragment"> <span class="keywordtype">void</span> myFunction ()
{
commentator.start (<span class="stringliteral">"Doing important work"</span>, <span class="stringliteral">"myFunction"</span>, 100);
<span class="keywordflow">for</span> (<span class="keywordtype">int</span> i = 0; i < 100; i++) {
...
commentator.progress ();
}
commentator.stop (MSG_DONE, <span class="stringliteral">"Task completed successfully"</span>);
}
</pre></div><p>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.</p>
<p>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.</p>
<p>In addition, commentator.report () allows reporting general messages, such as warnings, errors, and descriptions of internal progress.</p>
<p>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.</p>
<p>The commentator allows very precise control over what gets printed. See the Configuration section below. </p>
</div><hr/><h2>Member Function Documentation</h2>
<a class="anchor" id="a9b3772c898bc20f270af8d75ddc62090"></a><!-- doxytag: member="LinBox::Commentator::start" ref="a9b3772c898bc20f270af8d75ddc62090" args="(const char *description, const char *fn=(const char *) 0, unsigned long len=0)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">void start </td>
<td>(</td>
<td class="paramtype">const char * </td>
<td class="paramname"><em>description</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char * </td>
<td class="paramname"><em>fn</em> = <code>(const char *) 0</code>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">unsigned long </td>
<td class="paramname"><em>len</em> = <code>0</code> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Start an activity. </p>
<p>Inform the commentator that some new activity has begun. This is typically called at the beginning of a library function. </p>
<dl><dt><b>Parameters:</b></dt><dd>
<table class="params">
<tr><td class="paramname">description</td><td>A human-readable text description of the activity </td></tr>
<tr><td class="paramname">fn</td><td>The fully-qualified name of the function. Use 0 to use the same function as the surrounding activity (default 0) </td></tr>
<tr><td class="paramname">len</td><td>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) </td></tr>
</table>
</dd>
</dl>
<dl><dt><b>Examples: </b></dt><dd><a class="el" href="examples_2charpoly_8_c-example.html#a8">examples/charpoly.C</a>, and <a class="el" href="examples_2dot-product_8_c-example.html#a5">examples/dot-product.C</a>.</dd>
</dl>
</div>
</div>
<a class="anchor" id="a3a418a21b882e15baa44fe8bef7aca84"></a><!-- doxytag: member="LinBox::Commentator::stop" ref="a3a418a21b882e15baa44fe8bef7aca84" args="(const char *msg=MSG_DONE, const char *long_msg=(const char *) 0, const char *fn=(const char *) 0)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">void stop </td>
<td>(</td>
<td class="paramtype">const char * </td>
<td class="paramname"><em>msg</em> = <code>MSG_DONE</code>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char * </td>
<td class="paramname"><em>long_msg</em> = <code>(const char *) 0</code>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char * </td>
<td class="paramname"><em>fn</em> = <code>(const char *) 0</code> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Stop an activity. </p>
<p>Inform the commentator that the current activity has finished. </p>
<dl><dt><b>Parameters:</b></dt><dd>
<table class="params">
<tr><td class="paramname">msg</td><td>A short (one word) message describing the termination, e.g. "passed", "FAILED", "ok", etc. </td></tr>
<tr><td class="paramname">long_msg</td><td>A longer message describing the nature of the termination. May be 0, in which case msg is used. </td></tr>
<tr><td class="paramname">fn</td><td>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. </td></tr>
</table>
</dd>
</dl>
<dl><dt><b>Examples: </b></dt><dd><a class="el" href="examples_2charpoly_8_c-example.html#a9">examples/charpoly.C</a>, and <a class="el" href="examples_2dot-product_8_c-example.html#a6">examples/dot-product.C</a>.</dd>
</dl>
</div>
</div>
<a class="anchor" id="a9a39a88fa3e76ae8da02c2e49518ba1b"></a><!-- doxytag: member="LinBox::Commentator::progress" ref="a9a39a88fa3e76ae8da02c2e49518ba1b" args="(long k=-1, long len=-1)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">void progress </td>
<td>(</td>
<td class="paramtype">long </td>
<td class="paramname"><em>k</em> = <code>-1</code>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">long </td>
<td class="paramname"><em>len</em> = <code>-1</code> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Report progress in the current activity. </p>
<p>Inform the commentator that k steps of the current activity have been completed. </p>
<dl><dt><b>Parameters:</b></dt><dd>
<table class="params">
<tr><td class="paramname">k</td><td>Number of steps completed; use -1 to increment the current counter </td></tr>
<tr><td class="paramname">len</td><td>Total length of the operation; use -1 to use the existing length. This allows updating of inexact estimates of the number of steps. </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a class="anchor" id="a8dd0050b1bbb1722d2c754d6c85a4ec4"></a><!-- doxytag: member="LinBox::Commentator::report" ref="a8dd0050b1bbb1722d2c754d6c85a4ec4" args="(long level=LEVEL_IMPORTANT, const char *msg_class=INTERNAL_DESCRIPTION)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">std::ostream & report </td>
<td>(</td>
<td class="paramtype">long </td>
<td class="paramname"><em>level</em> = <code>LEVEL_IMPORTANT</code>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char * </td>
<td class="paramname"><em>msg_class</em> = <code>INTERNAL_DESCRIPTION</code> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Basic reporting. </p>
<p>Send some report string to the commentator </p>
<dl><dt><b>Parameters:</b></dt><dd>
<table class="params">
<tr><td class="paramname">level</td><td>Level of detail of the message </td></tr>
<tr><td class="paramname">msg_class</td><td>Type of message </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>A reference to the stream to which to output data </dd></dl>
<dl><dt><b>Examples: </b></dt><dd><a class="el" href="examples_2graph-charpoly_8_c-example.html#a5">examples/graph-charpoly.C</a>.</dd>
</dl>
</div>
</div>
<hr/>The documentation for this class was generated from the following files:<ul>
<li><a class="el" href="commentator_8h.html">commentator.h</a></li>
<li>commentator.C</li>
</ul>
</div>
<hr class="footer"/><address class="footer"><small>Generated on Tue Aug 30 2011 for linbox by 
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.7.4 </small></address>
</body>
</html>
