boost/test
2
0
Fork 0
mirror of https://github.com/boostorg/test.git synced 2026-01-22 17:52:18 +00:00
Code Issues Projects Releases Wiki Activity
Files
40d3cadedc1bb7a06f79c8094deef81e5bbe2c05
test/doc/components/execution_monitor/index.html
Gennadiy Rozental 06e7e97366 in progress 
[SVN r33093]
2006-02-23 19:29:10 +00:00

145 lines
9.3 KiB
HTML
Raw Blame History

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<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:
<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 call succeeds,
it returns the integer value returned by the monitored function. If any
of the following events occurs:
<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>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 thirdparameter
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 to report 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 Executiom Monitor facility provides a limited
ability to detect memory leaks during program execution and 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 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 trigger
memory leaks detection feature 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 -->18 February, 2006<!-- #EndDate -->
</P>
</DIV>
</DIV>
</BODY>
</HTML>
Reference in New Issue View Git Blame Copy Permalink