boost/test
2
0
Fork 0
mirror of https://github.com/boostorg/test.git synced 2026-01-26 19:12:10 +00:00
Code Issues Projects Releases Wiki Activity
Files
3e26dca83f3f9c35bbbba8cddae99c00a302882a
test/doc/components/execution_monitor/index.html
Gennadiy Rozental be8443b2dd *** empty log message *** 
[SVN r33388]
2006-03-19 12:16:57 +00:00

151 lines
9.5 KiB
HTML
Raw Blame History

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<HTML>
<HEAD>
<TITLE>The 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> &gt; <A href="../index.html">Components</A> &gt; <SPAN class="current_article">The
Execution Monitor</SPAN> </DIV>
<DIV class="body"> <IMG src="../../btl1.gif" alt="Boost Test logo"
height="43" width="252">
<H1>Boost Test Library: The Execution Monitor</H1>
<P class="page-toc"> <A href="#Introduction">Introduction</A><BR>
<A href="#Usage">Usage</A></P>
<P class="page-toc"><A href="#MemLeaks">Memory leaks detection </A><BR>
<A href="#Implementation">Implementation</A></P>
<P class="page-toc-indented"> <A href="execution_monitor.html">boost::execution_monitor</A><BR>
<A href="execution_exception.html">boost::execution_exception</A><BR>
<A href="execution_aborted.html">boost::execution_aborted</A> </P>
<P class="page-toc"> <A href="compilation.html">Compilation</A><BR>
<A href="#Examples">Examples</A><BR>
<A href="#Rationale">Design rationale</A></P>
<H2><A name="Introduction">Introduction</A></H2>
<P class="first-line-indented">Sometimes we need to call a function and make
sure that no user- or system-originated exceptions are being thrown by it.
Uniform exception reporting is also convenient. That's the purpose of the
Boost.Test's Execution Monitor.</P>
<P class="first-line-indented">The Execution Monitor is a lower-level
component of the Boost Test Library. It is the base for implementing
all other Boost.Test components but also can be used standalone to get
controlled execution of error-prone functions with a uniform error
notification. The Execution Monitor calls a user-supplied function in a
controlled environment, relieving users from messy error detection. </P>
<H2><A name="Usage">Usage</A></H2>
<P class="first-line-indented">All symbols in the Execution Monitor
implementation are located in the namespace boost. To use the Execution
Monitor you need to:</P>
<OL>
<LI> #include &lt;<A href="../../../../../boost/test/execution_monitor.hpp">boost/test/execution_monitor.hpp</A>&gt; </LI>
<LI> Make an instance of <A href="execution_monitor.html">boost::execution_monitor</A></LI>
<LI> Custom exception translators can be optionally registered with exception
classes for which you want special processing.</LI>
</OL>
<P class="first-line-indented">To start the monitored function, call the method <EM>execution_monitor::execute(
function_to_monitor, catch_system_exception, timeout )</EM>. If the call succeeds,
it returns the integer value returned by the monitored function. If any
of the following events occurs:</P>
<UL>
<LI> Uncaught C++ exception.</LI>
<LI>Hardware or software signal, trap, or other exception.</LI>
<LI>Timeout reached.</LI>
<LI>Debug assert event occurred (under Microsoft Visual C++ or compatible
compiler). </LI>
</UL>
<P>then the method execution_monitor::execute( ... ) throws the <A
href="execution_exception.html">boost::execution_exception</A>. The
method execution_monitor::execute( ... ) has two optional parameters
allowing you to modify its behavior. The second parameter is a boolean
flag catch_system_errors (default true) specifying whether or not
execution monitor should trap system level exceptions (second category
in above list). Set this value to false, for example, if you wish to
force coredump file creation. High-level Boost.Test components provide
a runtime parameter --catch_system_errors=yes for managing this
behavior in monitored unit tests. For some operating systems (not yet
Microsoft Windows) a third parameter is an integer timeout (in seconds)
for monitored function execution. Use this parameter to monitor code
with possible deadlocks or indefinite loops. For more detailed see <A
href="execution_monitor.html">execution monitor</A> specification. </P>
<P class="first-line-indented"><A name="caught_exception"></A>In
majority of the cases the monitored function doesn't need to throw the <A
href="execution_exception.html">boost::execution_exception</A> to
report an error in the Execution Monitor. If you want a custom error
message to be included into the execution_exception's error message,
use one of the following C++ types as an exception:</P>
<UL>
<LI>C string.</LI>
<LI>std:string.</LI>
<LI>any exception class in std::exception hierarchy.</LI>
</UL>
<P class="first-line-indented">If you need to abort the monitored
function without the Execution Monitor reporting any errors, you could
throw the <A href="execution_aborted.html">boost::execution_aborted</A>.
In case if you prefer or are forced to use your own exception types and
don't like &quot;unknown exception caught&quot; message, the Execution Monitor
allows you to register the translator for any exception types. You
could register as many independent translators as you like. See <A
href="execution_monitor.html">execution monitor</A> specification for
requirements on translator function. Also see below for usage example. </P>
<H2><A name="MemLeaks">Memory leaks detection </A></H2>
<P class="first-line-indented">The Execution Monitor facility provides
a limited ability to detect memory leaks during program execution, and
to break program execution on specific memory allocation order-number
(1 - first allocation of memory in program, 2 - second and so on).
Unfortunately this feature is, at the moment, implemented only for the
Microsoft family of compilers (and Intel, if it employs Microsoft C
Runtime Library). Also it could not be tuned per instance of the
monitor and is only triggered globally and reported after the whole
program execution is done. In a future this ought to be improved. An
interface is composed from two free functions residing in namespace
boost:</P>
<PRE class="code"><SPAN class="cpp-type">void</SPAN> <SPAN class="new-term">detect_memory_leak</SPAN>( <SPAN class="cpp-type">bool</SPAN> on_off );
<SPAN class="cpp-type">void</SPAN> <SPAN class="new-term">break_memory_alloc</SPAN>( <SPAN class="cpp-type">long</SPAN> mem_alloc_order_num );</PRE>
<P class="first-line-indented">Use function detect_memory_leaks to switch memory leaks detection on/off. Use break_memory_alloc to break a
program execution at allocation specified by <EM>mem_alloc_order_num </EM>argument.
<SPAN class="indented">High level Boost.Test components provide a
runtime parameter (--detect_memory_leak=yes or no) allowing one to
manage this feature during monitored unit tests.</SPAN></P>
<H2><A name="Implementation">Implementation</A></H2>
<P class="first-line-indented">The Execution Monitor is implemented in two
modules: one header file and one source file.</P>
<H4> <A href="../../../../../boost/test/execution_monitor.hpp">boost/test/execution_monitor.hpp</A>:</H4>
<P class="first-line-indented">defines abstract <A href="execution_monitor.html">execution
monitor</A> interfaces and implements <A href="execution_exception.html">execution
exception</A>.</P>
<H4><A href="../../../../../boost/test/execution_monitor.hpp">libs/test/execution_monitor.cpp</A>:</H4>
<P class="first-line-indented">provides <A href="execution_monitor.html">execution
monitor</A> implementation for all supported configurations, including
Microsoft structured exception based, UNIX signals. Note that when testing
requirements or user wishes preclude use of this file as a separate compilation
unit, it may be included as a header file. </P>
<P class="first-line-indented">Check <A href="compilation.html">compilation</A> instruction
to see how to build a standalone library for this component.</P>
<H2><A name="Examples">Examples</A></H2>
<P class="first-line-indented"><SPAN class="indented"><A href="../../examples/exec_mon_example.html">exec_mon_example</A></SPAN></P>
<P class="first-line-indented">For more examples of the Execution Monitor usage
see <A href="../prg_exec_monitor/index.html">Program Execution Monitor</A> or <A href="../utf/index.html">Unit
Test Framework.</A></P>
<H2><A name="Rationale">Design Rationale</A></H2>
<P class="first-line-indented"> While designing we were aware that it can be
used when no (or almost no) memory available. The Execution Monitor is intended
to be portable to as many platforms as possible.</P>
</DIV>
<DIV class="footer">
<DIV class="footer-body">
<P> &copy; <A name="Copyright">Copyright</A> <A href="mailto:boost-test%20at%20emailaccount%20dot%20com%20%28please%20unobscure%29">Gennadiy
Rozental</A> 2001-2006. <BR>
Distributed under the Boost Software License, Version 1.0. (See accompanying
file <A href="../../../../../LICENSE_1_0.txt">LICENSE_1_0.txt</A> or copy
at <A href="http://www.boost.org/LICENSE_1_0.txt">www.boost.org/LICENSE_1_0.txt</A>)</P>
<P>Revised:
<!-- #BeginDate format:Sw1 -->28 February, 2006<!-- #EndDate -->
</P>
</DIV>
</DIV>
</BODY>
</HTML>
Reference in New Issue View Git Blame Copy Permalink