Home > The Execution Monitor > User's guide

The Execution Monitor user's guide

The Execution Monitor is designed to solve the problem of executing potentially dangerous function that may result in any number of error conditions, in monitored environment that should prevent any undesirable exceptions to propagate out of function call and produce consistent result report for all outcomes. The Execution Monitor is able to produce informative report for all standard C++ exceptions and intrinsic types. All other exceptions are reported as unknown. If you prefer different message for your exception class or need to perform any action, the Execution Monitor supports custom exception translators. There are several other parameters of the monitored environment can be configured by setting appropriate properties of the Execution Monitor.
Execution Monitor 被設計用來解決執行可能導致很多錯誤情形的潛在危險的函數的問題, 在被監控的環境下,可以阻止任意非預料的異常傳播到函數調用之外,並對所有結果 (outcomes) 產生一致的結果報告。 Execution Monitor 可以對所有標準的 C++ 異常和內部類型產生有意義的報告。 所有其它的異常被報告為未知。 如果你想要為自己的異常提供不同的信息,或者執行某種操作,Execution Monitor 提供了 custom exception translators

All symbols in the Execution Monitor implementation are located in the namespace boost. To use the Execution Monitor you need to:
Execution Monitor 實現的所有符號都位於命名空間 boost。要使用 Execution Monitor 需要:

  1. #include <boost/test/execution_monitor.hpp>
    包含 <boost/test/execution_monitor.hpp>
  2. Make an instance of execution_monitor
    實例化一個 execution_monitor
  3. Optionally register custom exception translators for exception classes which require special processing.

Monitored function execution 被監控函數執行

To start the monitored function, invoke the method execution_monitor::execute and pass the monitored function as an argument. If the call succeeds, the method returns the result code produced by the monitored function. If any of the following conditions occur:
要執行被監控的函數,調用方法 execution_monitor::execute 並將要被監控的函數作為參數傳入。 如果調用成功,方法返回由被監控函數產生的結果代碼。 如果下面的情況發生:

  • Uncaught C++ exception. 未捕獲的 C++ 異常。
  • Hardware or software signal, trap, or other exception. 硬件或軟件的信號、陷入或其它異常。
  • Timeout reached. 超時
  • Debug assert event occurred (under Microsoft Visual C++ or compatible compiler).
    Debug 斷言事件 (Microsoft Visual C++ 或兼容的編譯器)

then the method throws the execution_exception. The exception contains unique error_code value identifying the error condition and the detailed message that can be used to report the error.
方法拋出 execution_exception 異常。 異常包含唯一的 error_code 用來標識錯誤情況和用來報告錯誤的詳細信息。

The execution monitor parameters  execution monitor 參數

All parameters are implemented as public read-write properties of class execution_monitor.
execution_monitor 的所有參數都被實現為公共的讀寫屬性。

The p_catch_system_errors property is a boolean flag (default value is true) specifying whether or not execution_monitor should trap system level exceptions (second category in above list). Set this property to false, for example, if you wish to force coredump file creation. The Unit Test Framework provides a runtime parameter --catch_system_errors=yes to alter the behavior in monitored test cases.
屬性 p_catch_system_errors 是布爾標籤 (默認為 true) 標識 execution_monitor 是否要陷入系統級異常 (上面列表第 2 項)。 將屬性設為 false,如果你要強迫生成核心轉儲 (coredump) 文件。 單元測試框架 (Unit Test Framework) 提供一個運行時參數 --catch_system_errors=yes 來改變被監控的測試用例的行為。

The p_auto_start_dbg property is a boolean flag (default value is false) specifying whether or not execution_monitor should try to attach debugger in case system error is caught.
屬性 p_auto_start_dbg 是布爾標籤 (默認為 false),標識當系統錯誤被捕獲時 execution_monitor 是否嘗試連接調試器。

The p_timeout property is an integer timeout (in seconds) for monitored function execution. Use this parameter to monitor code with possible deadlocks or indefinite loops. This feature is only available for some operating systems (not yet Microsoft Windows).
p_timeout 屬性是被監控函數執行超時的整數 (秒)。 使用這個參數監控代碼中可能存在的死鎖或無限循環。 這個特性只在幾個操作系統中可用 (目前不包括 Microsoft Windows)。

The p_use_alt_stack property is a boolean flag (default value is false) specifying whether or not execution_monitor should use an alternative stack for the sigaction based signal catching. When enabled the signals are delivered to the execution_monitor on a stack different from current execution stack, which is safer in case if it is corrupted by monitored function. For more details on alternative stack handling see appropriate manuals.
屬性 p_use_alt_stack 是布爾標籤 (默認為 false),標識當基於 sigaction 的信號被捕獲時 execution_monitor 是否使用另外的棧 (alternative stack)。 啟用這個屬性時,信號被派生到 execution_monitor 不同於當前運行棧的另一個棧上,這樣當被監控函數中斷時更安全。 關於選擇棧處理更多細節請參見相應的 manuals

The p_detect_fp_exceptions property is a boolean flag (default value is false) specifying whether or not execution_monitor should install hardware traps for the floating point exception on platforms where it's supported.
屬性 p_detect_fp_exceptions 是布爾標籤 (默認為 false),標識在平台支持浮點數異常時 execution_monitor 是否安裝硬件陷入。

Errors reporting and translation 錯誤報告和翻譯

If you need to report an error inside monitored function execution you have to throw an exception. Do not use the execution_exception - it's not intended to be used for this purpose. The simplest choice is to use one of the following C++ types as an exception:
如果需要在被監控函數執行中報告錯誤,那麼必須拋出異常。 不要使用 execution_exception - 它不是為這個目的使用的。 最簡單的選擇是使用下面的 C++ 類型之一作為異常:

  • C string.
  • std:string.
  • any exception class in std::exception hierarchy. 任何在 std::exception 層次內的異常類。

In case if you prefer to use your own exception classes or can't govern what exceptions are generated by monitored function and would like to see proper error message in a report, the Execution Monitor allows you to register the translator for any exception class. You can register as many independent translators as you like. See execution_monitor specification for requirements on translator function. Also see below for usage example.
如果你傾於使用自己的異常類或者不能確定被監控的函數會產生什麼異常,並且想要在報告中看到合適的錯誤信息, Execution Monitor 允許你註冊為任意的異常類註冊翻譯器 (translator)。 你可以註冊任意多個互相不依賴的翻譯器。 翻譯器函數的需求參見 execution_monitor 的定義。或看下面的使用示例。

Finally, if you need to abort the monitored function execution without reporting any errors, you can throw an exception execution_aborted. As a result the execution is aborted and zero result code is produced by the method execution_monitor::execute.
最後,如果想要中止被監控函數的執行又不報告任何錯誤,可以拋出 execution_aborted 異常。 這樣執行會被中止,並且方法 execution_monitor::execute 不生成結果代碼。

Memory leaks detection 內存洩漏檢測

The Execution Monitor provides a limited ability to detect memory leaks during program execution, and to break program execution on specific memory allocation order-number (1 - first allocation of memory in program, 2 - second and so on). Unfortunately this feature is, at the moment, implemented only for the Microsoft family of compilers (and Intel, if it employs Microsoft C Runtime Library). Also it can not be tuned per instance of the monitor and is only triggered globally and reported after the whole program execution is done. In a future this ought to be improved. An interface is composed from two free functions residing in namespace boost:
Execution Monitor 在程序執行中提供有限的檢測內存洩漏的能力,並在特定序號 (1 - 程序第一次申請內存,2 - 第二次,依次類推) 的內存分配時中斷程序執行。 不幸的是,這個特性現在只在 Microsoft 一族 (和 Intel,如果使用 Microsoft C 運行時庫) 的編譯器上實現。 同樣,它不能在每個監控器的實例上進行選擇,只能被全局觸發,並且在整個程序執行結束後報告。 將來這可能會被改進。接口由 boost 命名空間內兩個自由函數組成:

void detect_memory_leaks( bool on_off );
void break_memory_alloc( long mem_alloc_order_num );

Use function detect_memory_leaks to switch memory leaks detection on/off. Use break_memory_alloc to break a program execution at allocation specified by mem_alloc_order_num argument. The Unit Test Framework provides a runtime parameter (--detect_memory_leak=yes or no) allowing you to manage this feature during monitored unit tests.
使用函數 detect_memory_leaks 來設置內存洩漏檢查開關。 使用 break_memory_alloc 在參數 mem_alloc_order_num 指定的分配時中斷程序執行。 單元測試框架 (Unit Test Framework) 提供運行時參數 (--detect_memory_leak=yes 或 no) 允許在被監控的測試用例中管理這個特性。