The Execution Monitor reference

Header <boost/test/execution_monitor.hpp>

namespace boost {
  class execution_monitor;
  class execution_exception;
  class execution_aborted;
  class system_error;
}

Class execution_monitor

boost::execution_monitor — uniformly detects and reports the occurrence of several types of signals and exceptions, reducing various errors to a uniform execution_exception that is returned to a caller

Synopsis

class execution_monitor {
public:
  // construct/copy/destruct
  execution_monitor();

  // execution
  int execute(unit_test::callback0<int> const&);

  // registration
  template<typename Exception, typename ExceptionTranslator> 
    void register_exception_translator(ExceptionTranslator const&, 
                                       boost::type<Exception>* = 0);
  unit_test::readwrite_property<bool> p_catch_system_errors;
  unit_test::readwrite_property<bool> p_auto_start_dbg;
  unit_test::readwrite_property<int> p_timeout;
  unit_test::readwrite_property<int> p_use_alt_stack;
  unit_test::readwrite_property<bool> p_detect_fp_exceptions;
};

Description

`execution_monitor` public construct/copy/destruct

```
execution_monitor();
```
Throws:
Nothing.

Effects:
Constructs execution_monitor object.

`execution_monitor` execution

int execute(unit_test::callback0<int> const& F);

Parameters:

F

Returns:

Value returned by monitored function F call.

Throws:

execution_exception on detected uncaught C++ exception, a hardware or software signal, trap, or other monitored function F premature failure.

Notes:

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

`execution_monitor` registration

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

Throws:

Nothing.

Effects:

Registers translator function tr for an exception of type Exception. Translators get chained, so you can register as many as you want. The Exception type needs to be specified explicitly as the member function template argument. The translator function gets called when an exception of type Exception is thrown from within the monitored function. The translator receives a thrown exception object as its first argument. Result value of translator is ignored and no exception is reported if this function exits normally. But you can always rethrow the exception or throw a different one.

Class execution_exception

boost::execution_exception — uniformly reports monitored function execution problems

Synopsis

class execution_exception {
public:
  enum error_code;
};

Description

The class execution_exception is an exception used by the Execution Monitor to report problems detected during a monitored function execution. It intentionally does not allocate any memory so as to be safe for use when there is a lack of memory.

Type error_code

boost::execution_exception::error_code

Synopsis

enum error_code { no_error, user_error, cpp_exception_error, system_error, 
                  timeout_error, user_fatal_error, system_fatal_error };

Description

These values are sometimes used as program return codes. The particular values have been chosen to avoid conflicts with commonly used program return codes: values < 100 are often user assigned, values > 255 are sometimes used to report system errors. Gaps in values allow for orderly expansion.

	Note
	Only uncaught C++ exceptions are treated as errors. If the application catches a C++ exception, it will never reach the execution_monitor.

	Note
	The system errors include UNIX signals and Windows structured exceptions. They are often initiated by hardware traps.

The implementation decides what a fatal_system_exception is and what is just a system_exception. Fatal errors are so likely to have corrupted machine state (like a stack overflow or addressing exception) that it is unreasonable to continue execution.

Class execution_aborted

boost::execution_aborted — This is a trivial default constructible class. Use it to report graceful abortion of a monitored function execution.

Synopsis

class execution_aborted {
};

Class system_error

boost::system_error — This is a default constructible class. Use it to report failure in system call invocation.

Synopsis

class system_error {
public:
  // construct/copy/destruct
  system_error();
  unit_test::readonly_property<long> p_errno;
};

Description

`system_error` public construct/copy/destruct

```
system_error();
```
Throws:
Nothing.

Effects:
Constructs system_error object.