mirror of
https://github.com/boostorg/test.git
synced 2026-01-25 18:52:15 +00:00
184 lines
8.0 KiB
HTML
184 lines
8.0 KiB
HTML
<html>
|
|
|
|
<head>
|
|
<title>Program Execution Monitor</title>
|
|
<script language="javascript">var viso_path="js-lib"</script>
|
|
<script language="javascript" src="js-lib/core.js" > </script>
|
|
|
|
<script language="JavaScript">
|
|
JS.include( "btl.js" );
|
|
</script>
|
|
|
|
<script>put_screen_style();</script>
|
|
<link rel="stylesheet" type="text/css" href="style/btl_print.css" media="print" />
|
|
|
|
<meta http-equiv="Content-Language" content="en-us" />
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
|
|
</head>
|
|
|
|
<body onload="btl_menu_init()">
|
|
<div align="center">
|
|
<table class="body-table" cellspacing="3" >
|
|
<tr>
|
|
<td id="body">
|
|
|
|
<script language="Javascript">btl_header()</script>
|
|
|
|
<h1>Boost Test Library: Program Execution Monitor</h1>
|
|
|
|
<p class="page-toc">
|
|
<a href="#Introduction">Introduction</a><br>
|
|
<a href="#Benefits">Benefits</a><br>
|
|
<a href="#Specifications">Specifications</a><br>
|
|
<a href="#MonitorCompilation">Compilation</a><br>
|
|
<a href="#Example">Example Programs</a><br>
|
|
<a href="#Rationale">Rationale</a><br>
|
|
<a href="#Design">Design</a>
|
|
</p>
|
|
|
|
<h2><a name="Introduction">Introduction</a></h2>
|
|
|
|
<p class="1-line-indented">The Boost Test Library's Program Execution Monitor provides a replacement <b>main()</b>
|
|
function which calls a user-supplied <b>cpp_main()</b> function within a try
|
|
block. The supplied <b>main()</b> then catches and reports
|
|
exceptions, relieving users from messy error detection and reporting duties.</p>
|
|
<p>For use with the Program Execution Monitor, the traditional Hello World
|
|
program becomes:</p>
|
|
|
|
<pre class="code">#<span class="reserv-word">include</span> <iostream>
|
|
|
|
<span class="cpp-type">int</span> cpp_main( <span class="cpp-type">int</span>, <span class="cpp-type">char</span> *[] ) <span class="comment">// note name</span>
|
|
{
|
|
std::cout << <span class="literal">"Hello, world\n"</span>;
|
|
|
|
<span class="reserv-word">return</span> <span class="literal">0</span>;
|
|
}
|
|
</pre>
|
|
|
|
<p class="1-line-indented">It really is that simple - just change the name of your initial function from
|
|
main to <b>cpp_main()</b>. Do make sure the argc and arcv parameters are specified
|
|
(although you don't have to name them if you don't use them). Now you can
|
|
compile it and link with the Program Execution Monitor library.</p>
|
|
<p class="1-line-indented">When the above program executes, the output will be:</p>
|
|
<p class="test-output">
|
|
Hello, world<br>
|
|
no errors detected
|
|
</p>
|
|
<p class="1-line-indented">But what if some lower-level function had thrown a runtime_error with the
|
|
message "big trouble"? Then the output would look something like
|
|
this:</p>
|
|
<p class="test-output">
|
|
** exception: std::runtime_error: big trouble<br>
|
|
**** error return code 5<br>
|
|
********** errors detected; see standard output for details ***********
|
|
</p>
|
|
<p class="1-line-indented">And if a lower-level function had bubbled up a return code of 5, the output
|
|
would look something like this:</p>
|
|
<p class="test-output">
|
|
**** error return code 5<br>
|
|
*********** errors detected; see standard output for details ***********
|
|
</p>
|
|
<p class="1-line-indented">Note that the primary messages appear on standard output stream, while the final message
|
|
appears on standard error stream. This increases the visibility of error notification if
|
|
standard output and error streams are directed to different devices or files.
|
|
<script language="Javascript">put_ref_to_top()</script>
|
|
</p>
|
|
|
|
<h2><a name="Benefits">Benefits</a></h2>
|
|
|
|
<p class="1-line-indented">More uniform reporting of errors, particularly exceptions.</p>
|
|
<p><b>In production programs:</b></p>
|
|
|
|
<p class="1-line-indented">More uniform error reporting is particularly useful for programs running
|
|
unattended under control of scripts or batch files. Some operating systems pop
|
|
up message boxes if an uncaught exception occurs, and this requires operator
|
|
intervention. By converting such exceptions to non-zero program return codes,
|
|
the library makes the program a better citizen.</p>
|
|
|
|
<p class="1-line-indented">More uniform reporting of errors isn't a benefit to some programs,
|
|
particularly programs always run by hand by a knowledgeable person. So <b>
|
|
cpp_main()</b> wouldn't be worth using in that environment.</p>
|
|
<p><b>In test programs:</b></p>
|
|
<p class="1-line-indented">More uniform error reporting could be useful in test environments such as the boost
|
|
regression tests. But in this case it is preferable to use the <a href="test_exec_framework.htm">Test Execution Monitor</a>
|
|
or <a href="unit_test_framework.htm">Unit Test Framework</a>, cause they allows
|
|
you to use Test Tools and generate more detailed error information.</p>
|
|
|
|
<h2><a name="Specifications">Specifications</a> of the supplied main()</h2>
|
|
|
|
<p class="1-line-indented">Uniformly detects and reports the occurrence of several types of errors,
|
|
reducing the various errors to a uniform return value which is returned to the
|
|
host environment.</p>
|
|
<p>There are two intended uses:</p>
|
|
<ul>
|
|
<li>In production programs, which require no further action beyond naming the
|
|
top-level function <b>cpp_main()</b> instead of main().</li>
|
|
<li>In test frameworks, which supply <b>cpp_main()</b> to detect (or catch) test
|
|
specific errors, report them, and then return a presumably non-zero value.</li>
|
|
</ul>
|
|
<p>Requires:</p>
|
|
<p class="1-line-indented">A user-supplied <b>cpp_main()</b> function with same interface as main().</p>
|
|
Effects:
|
|
<p class="1-line-indented">Call <b>cpp_main</b>( argc, argv ) in a try block.</p>
|
|
<p>Treat as errors:</p>
|
|
<ul>
|
|
<li>Exceptions from <b>cpp_main()</b>.</li>
|
|
<li>Non-zero return from <b>cpp_main()</b>.</li>
|
|
</ul>
|
|
<p class="1-line-indented">Report errors to both cout (with details) and cerr (summary). Rationale:
|
|
Detail error reporting goes to cout so that it is properly interlaced with
|
|
other output, thus aiding error analysis. Summary goes to cerr in case cout is
|
|
redirected.</p>
|
|
|
|
<p>Returns:</p>
|
|
|
|
<p class="1-line-indented">non-zero if any error was detected, zero otherwise.
|
|
<script language="Javascript">put_ref_to_top()</script></p>
|
|
|
|
<h2>The Program <a name="MonitorCompilation">Execution Monitor compilation</a></h2>
|
|
<p class="1-line-indented">The Program Execution Monitor is supplied as an offline library and should be compiled and
|
|
linked with a test program. Following files, that are located in the Boost Test Library
|
|
src directory, compose the component:</p>
|
|
<p class ="indented">
|
|
<a href="../src/execution_monitor.cpp">execution_monitor.cpp</a><br>
|
|
<a href="../src/cpp_main.cpp">cpp_main.cpp</a>
|
|
</p>
|
|
|
|
<h2><a name="Example">Example</a> Program</h2>
|
|
<p class ="indented">
|
|
<a href="../example/prg_exec_example.cpp">prg_exec_example.cpp</a>
|
|
|
|
<h2><a name="Rationale">Rationale</a></h2>
|
|
<p class="1-line-indented">The components of a C++ program may report user-detected errors in several
|
|
ways, such as via a return value or throwing an exception. System-detected errors such as dereferencing
|
|
an invalid pointer are reported in other ways, totally operating system and compiler dependent.</p>
|
|
|
|
<p class="1-line-indented">Yet many C++ programs, both production and test, must run in an environment
|
|
where uniform reporting of errors is necessary. For example, converting otherwise uncaught exceptions
|
|
to non-zero program return codes allows many command line, script, or batch environments to continue
|
|
processing in a controlled manner. Even some GUI environments benefit from the unification of errors
|
|
into program return codes.</p>
|
|
|
|
<h2><a name="Design">Design</a></h2>
|
|
<p class="1-line-indented">The <a href="test_lib_design.htm">Boost Test Library Design</a>
|
|
document describes the relationship between the Program Execution Monitor and <a href="execution_monitor.htm">
|
|
Execution Monitor</a>.
|
|
|
|
<script language="Javascript">put_ref_to_top()</script></p>
|
|
<hr>
|
|
<p>© Beman Dawes 2000,
|
|
<script language="Javascript">contact_addess()</script>
|
|
<script language="Javascript">get_copyright_date()</script>
|
|
</p>
|
|
<p>Revised:
|
|
<!--webbot bot="Timestamp" S-Type="EDITED"
|
|
S-Format="%d %B, %Y" startspan -->09 August, 2002<!--webbot bot="Timestamp" endspan i-CheckSum="34422" -->
|
|
</p>
|
|
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</body>
|
|
</html>
|