|> The Execution Monitor > User's guide|
The Execution Monitor is designed to solve the problem of executing potentially dangerous function that may result in any number of error conditions, in monitored environment that should prevent any undesirable exceptions to propagate out of function call and produce consistent result report for all outcomes. The Execution Monitor is able to produce informative report for all standard C++ exceptions and intrinsic types. All other exceptions are reported as unknown. If you prefer different message for your exception class or need to perform any action, the Execution Monitor supports custom exception translators. There are several other parameters of the monitored environment can be configured by setting appropriate properties of the Execution Monitor.
All symbols in the Execution Monitor implementation are located in the namespace boost. To use the Execution Monitor you need to:
To start the monitored function, invoke the method
execution_monitor::execute and pass
the monitored function as an argument. If the call succeeds, the method returns the result code produced by the
monitored function. If any of the following conditions occur:
then the method throws the
execution_exception. The exception contains unique
error_code value identifying the error condition and the detailed message that can be used to report
All parameters are implemented as public read-write properties of class
The p_catch_system_errors property is a boolean flag (default value is true) specifying whether
execution_monitor should trap system level exceptions (second category in above list).
Set this property to false, for example, if you wish to force coredump file creation. The Unit Test Framework
provides a runtime parameter --catch_system_errors=yes to alter the behavior in monitored test cases.
The p_auto_start_dbg property is a boolean flag (default value is false) specifying whether or
execution_monitor should try to attach debugger in case system error is caught.
The p_timeout property is an integer timeout (in seconds) for monitored function execution. Use this parameter to monitor code with possible deadlocks or indefinite loops. This feature is only available for some operating systems (not yet Microsoft Windows).
The p_use_alt_stack property is a boolean flag (default value is false) specifying whether or
execution_monitor should use an alternative stack for the
sigaction based signal catching. When enabled the signals are delivered to the
execution_monitor on a stack different from current execution stack, which is safer in case
if it is corrupted by monitored function. For more details on alternative stack handling see appropriate
The p_detect_fp_exceptions property is a boolean flag (default value is false) specifying
whether or not
execution_monitor should install hardware traps for the floating point
exception on platforms where it's supported.
If you need to report an error inside monitored function execution you have to throw an exception. Do not use the
execution_exception - it's not intended to be used for this purpose. The simplest choice is
to use one of the following C++ types as an exception:
In case if you prefer to use your own exception classes or can't govern what exceptions are generated by monitored
function and would like to see proper error message in a report, the Execution Monitor allows you to register the
translator for any exception class. You can register as many independent translators as you like. See
execution_monitor specification for requirements on translator function. Also see below
for usage example.
Finally, if you need to abort the monitored function execution without reporting any errors, you can throw an
execution_aborted. As a result the execution is aborted and zero result code
is produced by the method
The Execution Monitor 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 can 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:
void detect_memory_leaks( bool on_off ); void break_memory_alloc( long mem_alloc_order_num );
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 mem_alloc_order_num argument. The Unit Test Framework provides a runtime parameter (--detect_memory_leak=yes or no) allowing you to manage this feature during monitored unit tests.