mirror of
https://github.com/boostorg/test.git
synced 2026-01-26 07:02:12 +00:00
124 lines
6.9 KiB
HTML
124 lines
6.9 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
|
|
|
|
<HTML>
|
|
<HEAD>
|
|
<TITLE>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="centered">
|
|
<TABLE class="body-table" cellspacing="3" >
|
|
<TR>
|
|
<TD id="body"> <A name='TOP'><IMG src='../../../c++boost.gif' width='277' height='86' alt="Boost logo"></A>
|
|
<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 <A href="#Specifications:monitor">boost::execution_monitor</A>
|
|
and overwrite the virtual method int execution_monitor::function(). To start the
|
|
monitored function call the execution_monitor::execute( timeout ) member function.
|
|
All symbols in the Execution Monitor implementation are located in the namespace
|
|
boost.<SPAN class='ref-to-top'><A href="#TOP"><IMG src="imgs/uarrow.gif" alt="reference to the top"></A></SPAN>
|
|
</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() <SPAN style="text-decoration: underline">doesn't</SPAN> 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>
|
|
<SPAN class="ref-to-top"><A href="#TOP"><IMG src="imgs/uarrow.gif" alt="reference to the top"></A></SPAN>
|
|
|
|
<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 <A href="#Specifications:monitor">boost::execution_monitor</A>.</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.
|
|
|
|
<SPAN class="ref-to-top"><A href="#TOP"><IMG src="imgs/uarrow.gif" alt="reference to the top"></A></SPAN></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_monitor.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. <SPAN class="ref-to-top"><A href="#TOP"><IMG src="imgs/uarrow.gif" alt="reference to the top"></A></SPAN>
|
|
</P>
|
|
<br>
|
|
<DIV class="footer">
|
|
<P>© <A href='mailto:rogeeff@emailaccount.com'>Gennadiy Rozental</A> 2001-2002
|
|
</P>
|
|
<P>Revised:
|
|
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
|
|
09 September, 2002
|
|
<!--webbot bot="Timestamp" endspan i-checksum="21096" -->
|
|
</P>
|
|
</DIV>
|
|
</TD>
|
|
</TR>
|
|
</TABLE>
|
|
</DIV>
|
|
</BODY>
|
|
</HTML> |