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 the error.

All parameters are implemented as public read-write properties of class execution_monitor.

The p_catch_system_errors property is a boolean flag (default value is true) specifying whether or not 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 not 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 not 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 manuals.

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 exception execution_aborted. As a result the execution is aborted and zero result code is produced by the method execution_monitor::execute.

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.