Boost logo

Boost Test Library: Execution Monitor

Home
Introduction
Benefits
Specifications
Compilation
Examples
Rationale
Design

Introduction

The Boost Test Library's Execution Monitor calls a user-supplied function in a controlled environment, relieving users from a messy error detection. To use the Execution Monitor derive a class from the boost::execution_monitor and overwrite the virtual method int execution_monitor::function(). To start the monitored function call the execution_monitor::execute( timeout ) member function. All symbols in the Execution Monitor implementation are located in the namespace boost.reference to the top

Benefits

Controlled execution of error prone functions with a uniform error notification.

Specification of boost::execution_monitor

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

Usage:

  1. Create class inherited from the class execution_monitor.
  2. Overwrite the virtual function int execution_monitor::function().
  3. Call the method execution_monitor::execute( timeout ). The timeout argument specifies seconds that elapse before a timer_error occurs. May be ignored on some platforms.

Effects:

Calls the execution_monitor::function() inside a try/catch block which may also include other unspecified platform dependent error detection code. Throws boost::execution_exception on an uncaught C++ exception, a hardware or software signal, trap, or other exception. execution_monitor::execute() doesn't consider it an error for the execution_monitor::function() to return a non-zero value.

Returns:

The integer value returned by the execution_monitor::function().

reference to the top

Specification of boost::execution_exception

class execution_exception {
public:
    enum error_code {
        cpp_exception_error,    // see note (1) below
        system_error,           // see note (2) below
        timeout_error,          // only detectable on certain platforms
        user_fatal_error,       // user reported fatal error
        system_fatal_error      // see note (2) below
    };

    error_code code() const;
    char const what() const;
};

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

Note 2: These errors include Unix signals and Windows structured exceptions. They are often initiated by hardware traps.

The implementation decides what is a fatal_system_exception 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. reference to the top

The Execution Monitor compilation

To use the Execution Monitor standalone you should include an execution_monitor.cpp into your project. It is also supplied as a part of all other Boost Test Library's components.

Examples

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

Rationale

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. While designing we should be aware that we can be in a situation with no (or almost no) memory available.

Design

The Boost Test Library Design document describes the relationship between the Execution Monitor and several other components. reference to the top