boost.png (6897 bytes) System 庫
Boost Home    Library Home   Tutorial   Reference
Contents 目錄
Introduction 簡介
Design Rationale 設計原理
History 歷史
Acknowledgements 鳴謝
Headers 頭文件
<boost/system/error_code.hpp>
<boost/system/system_error.hpp>
<boost/system/cygwin_error.hpp>
<boost/system/linux_error.hpp>
<boost/system/windows_error.hpp>

Introduction 簡介

Error conditions originating from the operating system or other low-level application program interfaces (API's) are typically reported via an integer representing an error code. When these low-level API calls are wrapped in portable code, such as in a portable library, some users want to deal with the error codes in portable ways. Other users need to get at the system specific error codes, so they can deal with system specific needs. The Boost System library provides simple, light-weight error_code objects that encapsulate system-specific error code values, yet also provide access to more abstract and portable error conditions via error_condition objects. Because error_code objects can represent errors from sources other than the operating system, including user-defined sources, each error_code and error_condition has an associated error_category.

來自操作系統或其它底層API的錯誤通常會以一個表示錯誤代碼的整數來報告。當這些底層API調用被包裝在可移植的代碼中時,例如在一個可移植的庫 中,有些用戶會希望以可移植的方式處理這些錯誤代碼。而其它用戶則可能需要得到系統特定的錯誤代碼,這樣他們可以處理系統特定的需要。Boost System 庫提供了簡單、輕量級的 error_code 對象,封裝系統特定的錯誤代碼值,此外還通過 error_condition 對像提供了對更為抽像和可移植的錯誤條件的訪問。因為 error_code 對象可以表示來自操作系統以外的錯誤,包括用戶自定義的來源,所以每個 error_code 和 error_condition 都有一個相關聯的 error_category.

An exception class,  system_error, is provided. Derived from std::runtime_error, it captures the underlying error_code for the problem causing the exception so that this important information is not lost.

本庫還提供一個異常類 system_error. 它派生自 std::runtime_error, 用於捕獲引起異常的問題的底層 error_code,以便不會丟失這些重要信息。

While exceptions are the preferred C++ default error code reporting mechanism, users of libraries dependent on low-level API's often need overloads reporting error conditions via error code arguments and/or return values rather than via throwing exceptions. Otherwise, when errors are not exceptional occurrences and must be dealt with as they arise, programs become littered with try/catch blocks, unreadable, and very inefficient. The Boost System library supports both error reporting by exception and by error code.

雖然異常是首選的C++缺省的錯誤代碼報告機制,但是使用依賴於底層API的庫的用戶通常需要通過錯誤代碼參數和/或返回值而不是拋出異常來報告錯誤條件。否則,當錯誤不是意外事件且必須被處理時,程序會變得充滿 try/catch 塊,不可讀並且非常低效。Boost System 庫既支持通過異常也支持通過錯誤代碼進行錯誤報告。

In addition to portable errors codes and conditions supported by the error_code.hpp header, system-specific headers support the Cygwin, Linux, and Windows platforms. These headers are effectively no-ops if included for platforms other than their intended target.

除了 error_code.hpp 頭文件所支持的可移植錯誤代碼和條件以外,系統特定的頭文件還支持 Cygwin, Linux, 和 Windows 平台。如果這些頭文件在它們所指定的目標以外的平台上被包含,則只是空操作而已。

Design Rationale 設計原理

Class error_code  and error_condition are designed as a value types so they can be copied without slicing and do not requiring heap allocation, but still have polymorphic behavior based on the error category. This is achieved by abstract base class error_category supplying the polymorphic behavior, and error_code and error_condition containing a pointer to an object of a type derived from error_category.

類 error_codeerror_condition 被設計為一種值類型,這樣它們可以不受限制地複製,並且不要求堆分配,但仍具有基於錯誤類別的多態行為。這是由抽像基類 error_category 所提供的多態行為達成的,error_codeerror_condition 包含一個指向某個派生自 error_category 的類型的對象的指針。

Many of the detailed design decisions were driven by the requirements that users to be able to add additional error categories, and that it be no more difficult to write portable code than system-specific code.

許多詳細設計的決定是由以下需求所驅動的,即用戶可以增加額外的錯誤類別,以及編寫可移植代碼不會比編寫系統特定代碼更難。

The operator<< overload for error_code eliminates a misleading conversion to bool in code like cout << ec, where ec is of type error_code. It is also useful in its own right.

operator<< 對於 error_code 的重載消除了在如下代碼中的容易令人誤解的到 bool 的轉換,如 cout << ec, 其中 ec 類型為 error_code. 這對於它的正確使用也有幫助。

History 歷史

N1975, Filesystem Library Proposal for TR2, accepted for Library Technical Report 2 (TR2) at the Berlin meeting, included additional components to supplement the Standard Library's Diagnostics clause. Since then, these error reporting components have received wider public scrutiny and enhancements have been made to the design. The enhanced version has been used by N2054, Networking Library Proposal for TR2, demonstrating that these error reporting components are useful beyond the original Filesystem Library.

N1975, TR2 的 Filesystem 庫建議,在柏林會議上被接受為 Library Technical Report 2 (TR2),包含了額外的組件,以補充標準庫的診斷條款。從那以後,這些錯誤報告組件已經接受了廣泛的公開審查,並且設計得到了改進。增強版本已經被用於 N2054, TR2 的 Networking 庫建議,事實證明這些錯誤報告組件要比原先的 Filesystem 庫更有用。

The original proposal viewed error categories as a binary choice between errno (i.e. POSIX-style) and the native operating system's error codes. The proposed components now allow as many additional error categories as are needed by either implementations or by users. The need to support additional error categories, for example, occurs in some networking library implementations because they are built on top of the POSIX getaddrinfo API that uses error codes not based on errno.

原先的建議書將錯誤類別視為 errno (即 POSIX 風格)和原生操作系統的錯誤代碼兩者之一的選擇。建議的組件目前允許更多其它錯誤類別,如具體實現或用戶所需要的。例如,對於支持額外錯誤類別的需求發生在某些網絡庫的實現上,因為它們構建在 POSIX getaddrinfo API 之上,它是使用錯誤代碼而不是基於 errno 的。

Acknowledgements 鳴謝

Christopher Kohlhoff and Peter Dimov made important contributions to the design. Comments and suggestions were also received from Pavel Vozenilek, Gennaro Prota, Dave Abrahams, Jeff Garland, Iain Hanson, Oliver Kowalke, and Oleg Abrosimov. Christopher Kohlhoff suggested several improvements to the N2066 paper. Johan Nilsson's comments led to several of the refinements in N2066 .


Revised February 23, 2008

c Copyright Beman Dawes, 1999

Distributed under the Boost Software License, Version 1.0. (See file LICENSE_1_0.txt or  www.boost.org/LICENSE_1_0.txt)