Part II. Boost Test Library: The Program Execution Monitor

| > The Program Execution Monitor > |

# Part II. Boost Test Library: The Program Execution Monitor

### Introduction

The components of a C++ program may report user-detected errors in several ways, such as via a return value or throwing an exception. System-detected errors such as dereferencing an invalid pointer are reported in other ways, totally operating system and compiler dependent.

Yet many C++ programs, both production and test, must run in an environment where uniform reporting of errors is necessary. For example, converting otherwise uncaught exceptions to non-zero program return codes allows many command line, script, or batch environments to continue processing in a controlled manner. Even some GUI environments benefit from the unification of errors into program return codes.

The Boost Test Library's Program Execution Monitor relieves users from messy error detection and reporting duties by providing a replacement function main() which calls a user-supplied cpp_main() function within a monitored environment. The supplied main() then uniformly detects and reports the occurrence of several types of errors, reducing them to a uniform return code which is returned to the host environment.

Uniform error reporting is particularly useful for programs running unattended under control of scripts or batch files. Some operating systems pop up message boxes if an uncaught exception occurs, and this requires manual intervention. By converting such exceptions into non-zero program return codes, the library makes the program a better citizen. More uniform reporting of errors isn't a benefit to some programs, particularly programs always run by hand of a knowledgeable person. So the Program Execution Monitor wouldn't be worth using in that environment.

Uniform error reporting can be also useful in test environments such as the Boost regression tests. Be aware though in such case it might be preferable to use the Unit Test Framework, cause it allows one to use the Testing tools and generate more detailed error information.

### Usage

To facilitate uniform error reporting the Program Execution Monitor supplies function main() as part if it's implementation. To use the Program Execution Monitor instead of regular function main your program is required to supply a function cpp_main() with same signature.

Here is the traditional Hello World program implemented using the Program Execution Monitor:

Example 1. The Program Execution Monitor: Hello World

    #include <iostream>
    #include <boost/test/included/prg_exec_monitor.hpp>

    //____________________________________________________________________________//

    int cpp_main( int, char* [] ) // note name cpp_main, not main.
    {
        std::cout << "Hello, world\n";

        return 0;
    }

    //____________________________________________________________________________//

`Source code` | | | `Show output`

    Hello, world

    no errors detected

It really is that simple - just change the name of your initial function from main() to cpp_main(). Do make sure the argc and argv parameters are specified (although you don't have to name them if you don't use them).

The Program Execution Monitor treats as errors:

- Exceptions thrown from cpp_main().
- Non-zero return from cpp_main().

So what if some function had thrown a runtime_error with the message "big trouble" and it's not trapped by any catch clause? Like in a following example:

Example 2. The Program Execution Monitor: standard exception detection

    #include <stdexcept>
    #include <boost/test/included/prg_exec_monitor.hpp>

    //____________________________________________________________________________//

    int foo() { throw std::runtime_exception( "big trouble" ); }

    //____________________________________________________________________________//

    int cpp_main( int, char* [] ) // note the name
    {
        foo();

        return 0;
    }

    //____________________________________________________________________________//

`Source code` | | | `Show output`

    **** exception(205): std::runtime_error: big trouble
    ******** errors detected; see standard output for details ********

Note that in both examples above we used single-header variant of the Program Execution Monitor. Alternatively we can build and link with standalone library. In case of static library we are not required to include any Program Execution Monitor related headers. To use dynamic library you are required to include `boost/test/prg_exec_monitor.hpp` and define BOOST_TEST_DYN_LINK during program compilation. The same header is required if you want to employ auto-linking feature.

Let's consider an example where function cpp_main() had bubbled up a return code of 5:

Example 3. The Program Execution Monitor: error return code detection

    #include <boost/test/prg_exec_monitor.hpp> // this header is optional

    //____________________________________________________________________________//

    int cpp_main( int, char* [] ) // note the name
    {
        return 5;
    }

    //____________________________________________________________________________//

`Source code` | | | `Show output`

    **** error return code: 5
    ******** errors detected; see standard output for details ********

The Program Execution Monitor reports errors to both cout (details) and cerr (summary). Primary detailed error messages appear on standard output stream so that it is properly interlaced with other output, thus aiding error analysis. While the final error notification message appears on standard error stream. This increases the visibility of error notification if standard output and error streams are directed to different devices or files.

The Program Execution Monitor's supplied main() will return following result codes:

- boost::exit_success - no errors
- boost::exit_failure - non-zero and non-boost::exit_success return code from cpp_main().
- boost::exit_exception_failure - cpp_main() throw an exception.

### Configuration

There are two aspects of the Program Execution Monitor behavior that you can customize at runtime. Customization is performed using environment variables.

Table 1. The Program Execution Monitor configuration environment variables

Flag | Usage
--- | ---
BOOST_TEST_CATCH_SYSTEM_ERRORS | allows customizing behavior of the Program Execution Monitor in regards of catching system errors. For more details about the meaning of this option see the Execution Monitor. If you want to prevent the Program Execution Monitor from catching system exception, set the value of this variable to "no". The default value is "yes".
BOOST_PRG_MON_CONFIRM | allows avoiding success confirmation message. Some users prefer to see a confirmation message in case if program successfully executed. While others don't like the clutter or any output is prohibited by organization standards. To avoid the message set the value of this variable to "no". The default value is "yes".

Last revised: , at |