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.
To use the Execution Monitor you need:
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:
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:
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.
The Execution Monitor is implemented in two modules: one header file and one source file.
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.
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.