Part II. Boost Test Library: The Program Execution Monitor

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.

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:

#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;
}

//____________________________________________________________________________//

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:

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:

#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;
}

//____________________________________________________________________________//

**** 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:

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

//____________________________________________________________________________//

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

//____________________________________________________________________________//

**** 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:

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