mirror of
https://github.com/boostorg/test.git
synced 2026-01-26 07:02:12 +00:00
120 lines
8.9 KiB
HTML
120 lines
8.9 KiB
HTML
<HTML>
|
|
<HEAD>
|
|
<TITLE>The Program Execution Monitor</TITLE>
|
|
<LINK rel="stylesheet" type="text/css" href="../../style/btl.css" media="screen">
|
|
<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>
|
|
<DIV class="header"> <A href="../../index.html">Boost.Test</A> > <A href="../index.html">Components</A> > <SPAN class="current_article">The
|
|
Program Execution Monitor</SPAN> </DIV>
|
|
<DIV class="body"> <IMG src='../../btl.gif' width='252' height='43' alt="Boost Test logo">
|
|
<H1>Boost Test Library: The Program Execution Monitor</H1>
|
|
<P class="page-toc"> <A href="#Introduction">Introduction</A><BR>
|
|
<A href="#Usage">Usage</A><BR>
|
|
<A href="#Configuration">Configuration</A><BR>
|
|
<A href="#Implementation">Implementation</A><BR>
|
|
<A href="compilation.html">Compilation</A><BR>
|
|
<A href="#Examples">Examples and tests</A><BR>
|
|
</P>
|
|
<H2><A name="Introduction">Introduction</A></H2>
|
|
<P class="first_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="first_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>
|
|
<P class="first_line_indented">The Boost Test Library's Program Execution Monitor relieves users from messy error detection
|
|
and reporting duties by providing a replacement function main() which calls a user-supplied <SPAN class="new-term">cpp_main()</SPAN>
|
|
function within a monitored environment. The supplied main() then uniformly detects and reports the occurrence of several
|
|
types of errors, reducing them to a uniform return code which is returned to the host environment.</P>
|
|
<P class="first_line_indented">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. More uniform reporting of errors isn't a benefit to some programs, particularly programs always run by
|
|
hand by a knowledgeable person. So the Program Execution Monitor wouldn't be worth using in that environment.</P>
|
|
<P class="first_line_indented">Uniform error reporting could be also useful in test environments such as the boost regression
|
|
tests. Be aware though in such case it might be preferable to use the <A href="../test_exec_monitor/index.html">Test Execution Monitor</A>
|
|
or the <A href="../unit_test_framework/index.html">Unit Test Framework</A>, cause they allows one to use <A href="../test_tools/index.html">Test
|
|
Tools</A> and generate more detailed errors information.</P>
|
|
<H2><A name="Usage">Usage</A></H2>
|
|
<P>Using 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="first_line_indented">It really is that simple - just change the name of your initial function from main() to cpp_main().
|
|
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="first_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="first_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(205): std::runtime_error: big trouble<BR>
|
|
******** errors detected; see standard output for details ********</P>
|
|
<P class="first_line_indented">And if a function cpp_main() 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="first_line_indented">Note that the primary error messages appear on standard output stream, while the final errors
|
|
notification 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. </P>
|
|
<H2><A name="Configuration">Configuration</A></H2>
|
|
<P class="first_line_indented">There are two aspects of the Program Execution Monitor behavior that you can customize at
|
|
runtime. Customization performed using environment variables.</P>
|
|
<P class="indented">BOOST_TEST_CATCH_SYSTEM_ERRORS - allows to customize behavior of the Execution Monitor in regards of
|
|
catching system errors. For more details about the meaning of this option see the Execution Monitor <A href="../execution_monitor/index.html#catch_system_errors">documentation</A>.
|
|
If you want to prevent the Program Execution Monitor from catching system exception, set the value of this variable to
|
|
<U>"no"</U>. The default value is "yes".</P>
|
|
<BR>
|
|
<P class="indented">BOOST_PRG_MON_CONFIRM - allows to avoid success confirmation message. Some users prefer to see a confirmation
|
|
message in case if program successfully executed. While others don't like the clutter or any output is prohibited by organization
|
|
standards. To avoid the message set the value of this variable to <U>"no"</U>. The default value is "yes".</P>
|
|
<H2><A name="Implementation">Implementation</A></H2>
|
|
<P class="first_line_indented">To monitor execution of user supplied function cpp_main() the Program Execution Monitor relies
|
|
on the Boost Test's <A href="../execution_monitor/index.html">Execution Monitor</A> . Also the Program Execution Monitor
|
|
supply function main() in <<A href="../../../src/cpp_main.cpp">libs/test/src/cpp_main.cpp</A>>. For the program
|
|
to link successfully user is required to supply a function cpp_main() with same interface as the main(). The Program Execution
|
|
Monitor treat as errors:</P>
|
|
<UL>
|
|
<LI>Exceptions thrown from cpp_main().</LI>
|
|
<LI>Non-zero return from cpp_main().</LI>
|
|
</UL>
|
|
<P class="first_line_indented">The Program Execution Monitor reports errors to both cout (with details) and cerr (summary).
|
|
Detailed 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. The Program Execution Monitor's supplied main() will return following
|
|
result codes: </P>
|
|
<UL>
|
|
<LI>boost::exit_success - no errors</LI>
|
|
<LI>boost::exit_failure - non-zero and non-boost::exit_success return code from cpp_main().</LI>
|
|
<LI>boost::exit_exception_failure - cpp_main() throw an exception.</LI>
|
|
</UL>
|
|
<P class="first_line_indented">Check <A href="compilation.html">compilation</A> instructions to see
|
|
how to build standalone library for this component.</P>
|
|
<H2><A name="Examples">Examples</A> and tests</H2>
|
|
<P class ="indented"> <A href="../../examples/prog_exec_monitor_example.html">prg_exec_example</A><BR>
|
|
<A href="../../tests/prg_exec_fail1.html">prg_exec_fail1</A><BR>
|
|
<A href="../../tests/prg_exec_fail2.html">prg_exec_fail2</A><BR>
|
|
<A href="../../tests/prg_exec_fail3.html">prg_exec_fail3</A><BR>
|
|
<A href="../../tests/prg_exec_fail4.html">prg_exec_fail4</A><BR>
|
|
</DIV>
|
|
<DIV class="footer">
|
|
<DIV class="footer-body">
|
|
<P>Copyright © <A href='mailto:rogeeff@emailaccount.com'>Gennadiy Rozental</A> 2001-2003.<BR>
|
|
Permission to copy, use, modify, sell and distribute this document is granted provided this copyright notice appears
|
|
in all copies. This document is provided "as is" without express or implied warranty and with no claim as to its suitability
|
|
for any purpose.</P>
|
|
<P>Revised: 9 June, 2003</P>
|
|
</DIV>
|
|
</DIV>
|
|
</BODY>
|
|
</HTML>
|