![]() Boost Test Library: Program Execution Monitor Home IntroductionThe Boost Test Library's Program Execution Monitor provides a replacement main() function which calls a user-supplied cpp_main() function within a try block. The supplied main() then catches and reports exceptions, relieving users from messy error detection and reporting duties. For use with the Program Execution Monitor, the traditional Hello World program becomes: #include <iostream> int cpp_main( int, char* [] ) // note name { std::cout << "Hello, world\n"; return 0; } It really is that simple - just change the name of your initial function from main to cpp_main(). Do make sure the argc and arcv parameters are specified (although you don't have to name them if you don't use them). Now you can compile it and link with the Program Execution Monitor library. When the above program executes, the output will be: Hello, world But what if some lower-level function had thrown a runtime_error with the message "big trouble"? Then the output would look something like this: ** exception: std::runtime_error: big trouble And if a lower-level function had bubbled up a return code of 5, the output would look something like this: **** error return code 5 Note that the primary messages appear on standard output
stream, while the final 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.
BenefitsMore uniform reporting of errors, particularly exceptions. In production programs:More 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 operator intervention. By converting such exceptions to 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 by a knowledgeable person. So cpp_main() wouldn't be worth using in that environment. In test programs:More uniform error reporting could be useful in test environments such as the boost regression tests. But in this case it is preferable to use the Test Execution Monitor or Unit Test Framework, cause they allows you to use Test Tools and generate more detailed error information. Specifications of the supplied main()Uniformly detects and reports the occurrence of several types of errors, reducing the various errors to a uniform return value which is returned to the host environment. There are two intended uses:
Requires: A user-supplied cpp_main() function with same interface as main(). Effects:Call cpp_main( argc, argv ) in a try block. Treat as errors:
Report errors to both cout (with details) and cerr (summary). Rationale: Detail error reporting goes to cout so that it is properly interlaced with other output, thus aiding error analysis. Summary goes to cerr in case cout is redirected. Returns: non-zero if any error was detected, zero otherwise.
The Program Execution Monitor compilationThe Program Execution Monitor is supplied as an offline library and should be compiled and linked with a test program. Following files, that are located in the Boost Test Library src directory, compose the component: execution_monitor.cpp You also have a choice to include all files constituting the Program Execution Monitor directly into your program. Use <boost/test/included/prg_exec_monitor.hpp> for this porpose. Example Program prg_exec_example RationaleThe 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. DesignThe Boost Test Library Design
document describes the relationship between the Program Execution Monitor and
Execution Monitor. |