Class execution_monitor

boost::execution_monitor — Function execution monitor.

Synopsis

// In header: <boost/test/execution_monitor.hpp>


class execution_monitor {
public:

  // public member functions
  execution_monitor();
  int execute(boost::function< int()> const &);
  void vexecute(boost::function< void()> const &);
  template<typename ExceptionType, typename ExceptionTranslator> 
    void register_exception_translator(ExceptionTranslator const &, 
                                       const_string = const_string(), 
                                       boost::type< ExceptionType > * = 0);
  void erase_exception_translator(const_string);
  template<typename ExceptionType> 
    void erase_exception_translator(boost::type< ExceptionType > * = 0);

  // private member functions
  int catch_signals(boost::function< int()> const &);

  // public data members
  unit_test::readwrite_property< bool > p_catch_system_errors;  // Should monitor catch system errors. 
  unit_test::readwrite_property< bool > p_auto_start_dbg;  // Should monitor try to attach debugger in case of caught system error. 
  unit_test::readwrite_property< unsigned long int > p_timeout;  // Specifies the seconds that elapse before a timer_error occurs. 
  unit_test::readwrite_property< bool > p_use_alt_stack;  // Should monitor use alternative stack for the signal catching. 
  unit_test::readwrite_property< unsigned > p_detect_fp_exceptions;  // Should monitor try to detect hardware floating point exceptions (!= 0), and which specific exception to catch. 
};

Description

This class is used to uniformly detect and report an occurrence of several types of signals and exceptions, reducing various errors to a uniform execution_exception that is returned to a caller.

The execution_monitor behavior can be customized through a set of public parameters (properties) associated with the execution_monitor instance. All parameters are implemented as public unit_test::readwrite_property data members of the class execution_monitor.

`execution_monitor` public member functions

```
execution_monitor();
```
Default constructor initializes all execution monitor properties.
```
int execute(boost::function< int()> const & F);
```
Execution monitor entry point for functions returning integer value.
This method executes supplied function F inside a try/catch block and also may include other unspecified platform dependent error detection code.

This method throws an execution_exception on an uncaught C++ exception, a hardware or software signal, trap, or other user exception.

Note

execute() doesn't consider it an error for F to return a non-zero value.

See Also: vexecute

Parameters:

F

Function to monitor

Returns:

value returned by function call F().
```
void vexecute(boost::function< void()> const & F);
```
Execution monitor entry point for functions returning void.
This method is semantically identical to execution_monitor::execute, but doesn't produce any result code.

See Also: execute

Parameters:

F

Function to monitor

	Note
execute() doesn't consider it an error for F to return a non-zero value.

template<typename ExceptionType, typename ExceptionTranslator> 
  void register_exception_translator(ExceptionTranslator const & tr, 
                                     const_string tag = const_string(), 
                                     boost::type< ExceptionType > * = 0);

Registers custom (user supplied) exception translator.

This method template registers a translator for an exception type specified as a first template argument. For example

void myExceptTr( MyException const& ex ) { /*do something with the exception here*/}
em.register_exception_translator<MyException>( myExceptTr );

The translator should be any unary function/functor object which accepts MyException const&. This can be free standing function or bound class method. The second argument is an optional string tag you can associate with this translator routine. The only reason to specify the tag is if you plan to erase the translator eventually. This can be useful in scenario when you reuse the same execution_monitor instance to monitor different routines and need to register a translator specific to the routine being monitored. While it is possible to erase the translator based on an exception type it was registered for, tag string provides simpler way of doing this.

Parameters:

`tr`	translator function object with the signature void (ExceptionType const&)
`tag`	tag associated with this translator

Template Parameters:

`ExceptionType`	type of the exception we register a translator for
`ExceptionTranslator`	type of the translator we register for this exception

```
void erase_exception_translator(const_string tag);
```
Erases custom exception translator based on a tag.
Use the same tag as the one used during translator registration

Parameters:

tag

tag associated with translator you wants to erase
```
template<typename ExceptionType> 
  void erase_exception_translator(boost::type< ExceptionType > * = 0);
```
Erases custom exception translator based on an exception type.
tparam ExceptionType Exception type for which you want to erase the translator

`execution_monitor` private member functions

int catch_signals(boost::function< int()> const & F);

`execution_monitor` public public data members

```
unit_test::readwrite_property< bool > p_catch_system_errors;
```
The p_catch_system_errors property is a boolean flag (default value is true) specifying whether or not execution_monitor should trap system errors/system level exceptions/signals, which would cause program to crash in a regular case (without execution_monitor). 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.
```
unit_test::readwrite_property< bool > p_auto_start_dbg;
```
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.
```
unit_test::readwrite_property< unsigned long int > p_timeout;
```
The p_timeout property is an integer timeout (in microseconds) for monitored function execution. Use this parameter to monitor code with possible deadlocks or infinite loops. This feature is only available for some operating systems (not yet Microsoft Windows).
```
unit_test::readwrite_property< bool > p_use_alt_stack;
```
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.
```
unit_test::readwrite_property< unsigned > p_detect_fp_exceptions;
```
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.

Boost C++ Libraries