Boost Test Library: The Execution Monitor

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.

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.

Usage

To use the Execution Monitor you need:

Include <boost/test/execution_monitor.hpp>
Make an instance of boost::execution_monitor
Optionally register custom exception translators for exception classes you want special processing

To start the monitored function, call the method execution_monitor::execute( function_to_monitor, catch_system_exception, timeout ). If call succeeds, it returns the integer value returned by the monitored function. If any of the following events occurs:

Uncaught C++ exception
hardware or software signal, trap, or other exception
Timeout reached
debug assert event occurred (under Microsoft Visual C++ or compatible compiler)

the method execution_monitor::execute( ... ) throws the boost::execution_exception. The method execution_monitor::execute( ... ) has two optional arguments. The second argument catch_system_exception 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 third argument timeout 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.

In majority of the cases you don't need to throw the boost::execution_exception in the 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:

C string
std:string
any exception class in std::exception hierarchy

If you need to abort the monitored function without the Execution Monitor to report any errors, you could throw the boost::execution_aborted. 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 execution monitor specification for requirements on translator function. Also see below for usage example.

Implementation

The Execution Monitor is implemented in two modules: one header file and one source file.

boost/test/execution_monitor.hpp:

defines abstract execution monitor interfaces and implements execution exception.

libs/test/execution_monitor.cpp:

provides execution monitor 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.

Check compilation instruction to see how to build standalone library for this component.

Examples

exec_mon_example

For more examples of usage of Execution Monitor see Program Execution Monitor or Unit Test Framework.

Design Rationale

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.