mirror of
https://github.com/boostorg/test.git
synced 2026-01-26 19:12:10 +00:00
134 lines
6.5 KiB
HTML
134 lines
6.5 KiB
HTML
<html>
|
|
|
|
<head>
|
|
<title>Execution Monitor</title>
|
|
<script language="javascript">var viso_path="js-lib"</script>
|
|
<script language="javascript" src="js-lib/core.js" > </script>
|
|
|
|
<link id="screen_style" 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=windows-1252" />
|
|
|
|
<script language="JavaScript">
|
|
include ( "btl.js" );
|
|
</script>
|
|
</head>
|
|
|
|
<body onload="btl_menu_init()">
|
|
<div align="center">
|
|
<table class="body-table" cellspacing="3" >
|
|
<tr>
|
|
<td>
|
|
|
|
<script language="Javascript">btl_header()</script>
|
|
|
|
<h1>Boost Test Library: Execution Monitor</h1>
|
|
|
|
<p class="page-toc">
|
|
<a href="#Introduction">Introduction</a><br>
|
|
<a href="#Benefits">Benefits</a><br>
|
|
<a href="#Specifications:monitor">Specifications</a><br>
|
|
<a href="#MonitorCompilation">Compilation</a><br>
|
|
<a href="#Examples">Examples</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 Execution Monitor calls a user-supplied function in a
|
|
controlled environment, relieving users from a messy error detection. To use the Execution Monitor
|
|
derive a class from the <b><a href="#Specifications:monitor">boost::execution_monitor</a></b>
|
|
and overwrite the virtual method int <b>execution_monitor::function</b>(). To start the monitored
|
|
function call the <b>execution_monitor<u>:</u>:execute</b>( timeout ) member
|
|
function. All symbols in the Execution Monitor implementation are located in the namespace boost.
|
|
<script language="Javascript">put_ref_to_top()</script>
|
|
</p>
|
|
|
|
<h2><a name="Benefits">Benefits</a></h2>
|
|
<p class="1-line-indented">Controlled execution of error prone functions with a uniform error notification.</p>
|
|
|
|
<h2><a name="Specifications:monitor">Specification</a> of boost::execution_monitor</h2>
|
|
<p class="1-line-indented">
|
|
boost::execution_monitor uniformly detects and reports the occurrence of several types of signals and exceptions, reducing various errors
|
|
to a uniform <a href="#Specifications:exception">boost::execution_exception</a> which is returned to a caller.</p>
|
|
<p>Usage:</p>
|
|
<ol>
|
|
<li>Create class inherited from the class <span class="new-term">execution_monitor</span>.</li>
|
|
<li>Overwrite the virtual function int execution_monitor::<span class="new-term">function</span>().</li>
|
|
<li>Call the method execution_monitor::<span class="new-term">execute</span>( timeout ). The <span class="new-term">timeout</span>
|
|
argument specifies seconds that elapse before a <a href="#Specifications:exception">timer_error</a>
|
|
occurs. May be ignored on some platforms.
|
|
</li>
|
|
</ol>
|
|
<p>Effects:</p>
|
|
<p class="indented">
|
|
Calls the execution_monitor::function() inside a try/catch block which may also include other unspecified platform dependent error detection code.
|
|
Throws <a href="#Specifications:exception">boost::execution_exception</a> on an uncaught C++ exception,
|
|
a hardware or software signal, trap, or other exception. execution_monitor::execute() <u>doesn't</u> consider it an error for
|
|
the execution_monitor::function() to return a non-zero value.
|
|
</p>
|
|
<p>Returns:<p>
|
|
<p class="indented">
|
|
The integer value returned by the execution_monitor::function().
|
|
</p>
|
|
<script language="Javascript">put_ref_to_top()</script>
|
|
<h2><a name="Specifications:exception">Specification</a> of boost::execution_exception</h2>
|
|
<pre class="code"><span class="reserv-word">enum</span> <span class="new-term">execution_exception</span> {
|
|
<span class="reserv-word">public</span>:
|
|
<span class="reserv-word">enum</span> error_code {
|
|
cpp_exception_error, <span class="comment">// see note (1) below</span>
|
|
system_error, <span class="comment">// see note (2) below</span>
|
|
timeout_error, <span class="comment">// only detectable on certain platforms</span>
|
|
user_fatal_error, <span class="comment">// user reported fatal error</span>
|
|
system_fatal_error <span class="comment">// see note (2) below</span>
|
|
};
|
|
|
|
error_code code() <span class="reserv-word">const</span>;
|
|
<span class="cpp-type">char</span> <span class="reserv-word">const</span> what() <span class="reserv-word">const</span>;
|
|
};
|
|
</pre>
|
|
|
|
<p> Note 1: Only uncaught C++ exceptions are treated as errors. If the application catches a C++ exception, it will never reach the
|
|
<b><a href="#Specifications:monitor">boost::execution_monitor</a></b>.</p>
|
|
<p> Note 2: These errors include Unix signals and Windows structured exceptions. They are often initiated by hardware traps.</p>
|
|
<p class="1-line-indented"> The implementation decides what is a fatal_system_exception and what is just a system_exception. Fatal errors are so likely to have corrupted machine state (like a stack overflow or addressing exception) that it is
|
|
unreasonable to continue execution.
|
|
<script language="Javascript">put_ref_to_top()</script></p>
|
|
<h2>The <a name="MonitorCompilation">Execution Monitor compilation</a></h2>
|
|
<p class="1-line-indented">To use the Execution Monitor standalone you should include an
|
|
<a href="../src/execution_monitor.cpp">execution_monitor.cpp</a> into your
|
|
project. It is also supplied as a part of all other Boost Test Library's components.</p>
|
|
<h2><a name="Examples">Examples</a></h2>
|
|
|
|
<p class="1-line-indented">For examples of usage of Execution Monitor see <a href="prg_exec_framework.htm">Program
|
|
Execution Monitor</a> or <a href="unit_test_framework.htm">Unit Test Framework.</a> </p>
|
|
|
|
<h2><a name="Rationale">Rationale</a></h2>
|
|
<p class="1-line-indented">Sometimes we need to call a function and make sure that no user or
|
|
system originated exception are being thrown by it. Also uniform exception reporting would be convenient.
|
|
While designing we should be aware that we can be in a situation with no (or
|
|
almost no) memory available.</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 Execution Monitor and several other components.
|
|
<script language="Javascript">put_ref_to_top()</script>
|
|
</p>
|
|
<hr>
|
|
<p>©
|
|
<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 -->29 July, 2002<!--webbot bot="Timestamp" endspan i-checksum="21096" -->
|
|
</p>
|
|
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</body>
|
|
</html> |