Home > The Program Execution Monitor >
PrevNext

Part II. Boost Test Library: The Program Execution Monitor

Table of Contents

Implementation
Compilation

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.
C++ 程序的組件會用很多方式報告用戶檢測的錯誤,例如返回值或拋出異常。 系統檢測的錯誤如解引用無效指針,用另一種方式報告,是操作系統和編譯器相關的。

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.
但很多 C++ 程序,無論是工業級還是測試級,都必須運行在統一報告錯誤的環境下。 例如,將未捕獲的異常轉換為程序非零返回值可以使很多命令行、腳本或批處理環境以可控的方式順序執行。 即使是一些 GUI 環境同樣可以從一致的程序返回代碼中獲益。

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.
Boost Test 庫的 Program Execution Monitor 提供一個替代的 main() 函數, 在被監控的環境下調用用戶提供的 cpp_main() 函數,以此來將用戶從繁瑣的錯誤檢測和報告中解脫出來。 提供的 main() 函數對多種類型的錯誤進行一致的檢測和報告,並加它們用返回代碼的方式一致地返回到宿主環境中。

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.
統一的錯誤報告在程序運行在無人看管的腳本或批處理文件中時尤其有用。 有些操作系統在未捕獲異常發生時會彈出消息對話框,這需要人為的干預。 通過將這樣的異常轉換為非零的程序返回代碼,庫使得程序成為更好的公民。 對某些程序,尤其是總由有經常的人手工運行的程序來說,更加一致的錯誤報告並不有益。 所以 Program Execution Monitor 並不適用於那種環境。

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.
一致的錯誤報告在某些測試環境中同樣有用,例如 Boost 的回歸測試。 當然在那種情況下最好使用單元測試框架 (Unit Test Framework), 因為這樣可以使用 測試工具 (Testing tools),並產生更詳細的錯誤信息。

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.
為了使得一致的錯誤報告更容易,Program Execution Monitor 提供了 main() 函數作為其實現的一部分。 要使用 Program Execution Monitor 替換普通的 main 函數,程序需要以相同的簽名提供函數 cpp_main()。

Here is the traditional Hello World program implemented using the Program Execution Monitor:
下面是使用 Program Execution Monitor 實現的 Hello World 程序:

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).
這非常簡單 - 只是將起始函數的名稱從 main() 改為 cpp_main()。 確保定義了 argc 和 argv 參數 (即使你不使用它們也不為它們命名)。

The Program Execution Monitor treats as errors:
Program Execution Monitor 將下面情況視為錯誤:

  • Exceptions thrown from cpp_main(). 從 cpp_main() 中拋出異常
  • Non-zero return from cpp_main(). 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:
如果某個函數拋出 runtime_error 和信息 "big trouble" 並且沒有被捕獲到,會產生什麼結果呢?見下面例子:

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.
在上面的兩個例子中我們都使用的是單個頭文件的 Program Execution Monitor。我們同樣可以生成並鏈接獨立的庫。 如果使用靜態庫,我們不需要包含任何 Program Execution Monitor 相關的頭文件。 如果使用動態庫,則需要包含 boost/test/prg_exec_monitor.hpp 並在程序編譯時定義 BOOST_TEST_DYN_LINK。 如果要使用自動鏈接 (auto-linking) 特性也需要使用這個頭文件。

Let's consider an example where function cpp_main() had bubbled up a return code of 5:
下面的例子我們看看函數 cpp_main() 返回代碼 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.
Program Execution Monitor 將錯誤同時報告到 cout (詳細) 和 cerr (概述)。 主要的詳細的錯誤信息出現在標準輸出流中,這樣就可以和其它輸出交織在一起,用來為錯誤分析提供幫助。 而最後的錯誤通知信息出現在標準錯誤流中。 如果標準輸出和錯誤流重定向到不同的設備或文件中的話,這增加了錯誤通知的可見性。

The Program Execution Monitor's supplied main() will return following result codes:
Program Execution Monitor 提供的 main() 可以返回下面的結果代碼:

  • 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.
Program Execution Monitor 有兩方面的行為可以在運行時自定義。自定義是通過環境變量設置的。

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".
自定義 Program Execution Monitor 在捕獲系統錯誤時的行為。 關於這個選項的更多信息請參見 Execution Monitor。 如果想要阻止 Program Execution Monitor 捕獲系統異常,將這個變量設置為 "no"。默認為 "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".
避免輸出成功確認信息。 如果程序成功執行,有些用戶喜歡看到確認信息。 而另一些用戶不喜歡這種混亂的,或是妨礙整理標準輸出的信息。 要避免輸出這些信息,將變量值設置為 "no"。默認為 "yes"。

Last revised: , at


PrevUpHomeNext