1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
|
<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> > <A href="../index.html">Components</A>
> <SPAN class="current_article">The Execution Monitor</SPAN> </DIV>
<DIV class="body"> <IMG src='../../btl1.gif' width='252' height='43' alt="Boost Test logo">
<H1>Boost Test Library: The Execution Monitor</H1>
<P class="page-toc"> <A href="#Introduction">Introduction</A><BR>
<A href="#Usage">Usage</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>
</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 exception are being thrown by it. Also uniform exception reporting would be convenient.
That's the purpose the Boost Test's Execution Monitor component serves to.</P>
<P class="first-line-indented">The Execution Monitor is a lower level component of Boost Test Library.
It's used as a base for implementing all other Boost Test components but also could be used standalone
to get a benefit of 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 a messy error detection. All symbols in the Execution Monitor implementation are located in the
namespace boost. </P>
<H2><A name="Usage">Usage</A></H2>
<P class="first-line-indented">To use the Execution Monitor you need:
<OL>
<LI> Include <<A href="../../../../../boost/test/execution_monitor.hpp">boost/test/execution_monitor.hpp</A>>
</LI>
<LI> Derive your class from the <A href="execution_monitor.html">boost::execution_monitor</A> </LI>
<LI> Override the virtual method <EM>int execution_monitor::function()</EM> with the code you want
to monitor </LI>
</OL>
<P class="first-line-indented">To start the monitored function, call the method <EM>execution_monitor::execute(
catch_system_exception, timeout )</EM>. If call succeeds, it returns the integer value returned by
the execution_monitor::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>
the method execution_monitor::execute( ... ) throws the <A href="execution_exception.html">boost::execution_exception</A>.
The method execution_monitor::execute( ... ) has two optional arguments. The first argument <EM><A name="catch_system_errors">catch_system_exception</A></EM>
is a boolean argument specifying whether or not execution monitor should catch system and fatal exceptions
(second category in above list). Default value is true. You may want to set this value to false, for
example, in case if you willing to force core file creation. High level Boost Test components provide
a runtime parameter managing this behavior. The second argument <EM>timeout</EM> is a time-out value
that specifies seconds that elapse before a timeout error occurs. Note though, that in current implementation
timeout support is limited and it may be ignored on some platforms. By default there is no time-out
for the call. Use this parameter to monitor code with possible deadlocks or indefinite loops.
<P class="first-line-indented"><A name="caught_exception"></A>In majority of the cases you don't need to throw the <A href="execution_exception.html">boost::execution_exception</A>
in monitored function to be able to report an error to the Execution Monitor. If you want your error
message to be propagated to 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">In case if you prefer or forced to use your own exception types and don't like "unknown exception caught" 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="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 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 usage of Execution Monitor 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 should be aware that we can be in a situation with
no (or almost no) memory available. The Execution Monitor intended to be portable to as many platforms
as possible.</P>
</DIV>
<DIV class="footer">
<DIV class="footer-body">
<P> © <A name="Copyright">Copyright</A> <A href='mailto:boost-test at emailaccount dot com (please unobscure)'>Gennadiy Rozental</A> 2001-2004. <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 -->24 May, 2004<!-- #EndDate --> </P>
</DIV>
</DIV>
</BODY>
</HTML>
|
