feedc0de/boost_system
1
0
Fork 0
forked from boostorg/system
Code Pull Requests Activity

Update introduction

Browse Source
This commit is contained in:
Peter Dimov
2021-11-10 20:36:57 +02:00
parent 7dce2e3f42
commit 83a306f3bf
1 changed files with 60 additions and 32 deletions
Download Patch File Download Diff File Expand all files Collapse all files

92
doc/system/introduction.adoc
View File

@ -1,6 +1,6 @@
//// ////
Copyright 2003-2017 Beman Dawes Copyright 2003-2017 Beman Dawes
Copyright 2018 Peter Dimov Copyright 2018, 2021 Peter Dimov
Distributed under the Boost Software License, Version 1.0. Distributed under the Boost Software License, Version 1.0.
@ -12,39 +12,67 @@ http://www.boost.org/LICENSE_1_0.txt
# Introduction # Introduction
:idprefix: intro_ :idprefix: intro_
Error conditions originating from the operating system or other low-level Errors originating from the operating system or other low-level application
application program interfaces (API's) are typically reported via an integer program interfaces (APIs) are typically reported via an integer representing
representing an error code. When these low-level API calls are wrapped in an error code, either by returning the code directly from the function (e.g.
portable code, such as in a portable library, some users want to deal with the `pthread_mutex_init`) or by using a side channel such as the `errno`
error codes in portable ways. Other users need to get at the system specific pseudo-variable under POSIX or `GetLastError()` under Windows.
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 However, these integer error values can only be interpreted when their source
operating system, including user-defined sources, each `error_code` and is known. The value 5 under Windows means `ERROR_ACCESS_DENIED` when returned
`error_condition` has an associated `error_category`. by `GetLastError()`, but `EIO` when retrieved from `errno`. And conversely,
the same error condition "access denied" is represented by the value 5 when
returned by `GetLastError()` and 13 (`EACCES`) when retrieved from `errno`.
An exception class, `system_error`, is provided. Derived from This means that in order for code to be able to handle errors from both
`std::runtime_error`, it captures the underlying `error_code` for the problem sources (to retrieve a text message describing the error, or to check whether
causing the exception so that this important information is not lost. the error means "access denied"), it needs to know where the integer error
value originated. For this to be possible, the integer error value needs to
be accompanied by a piece of information identifying the source.
While exceptions are the preferred {cpp} default error code reporting Boost.System provides a framework in which this is possible. Errors are
mechanism, users of libraries dependent on low-level API's often need overloads represented by a class `error_code` which contains both the error value and
reporting error conditions via error code arguments and/or return values rather a pointer to their source (called "category"), represented as a class derived
than via throwing exceptions. Otherwise, when errors are not exceptional from `error_category`.
occurrences and must be dealt with as they arise, programs become littered with
try/catch blocks, unreadable, and inefficient. The Boost System library
supports both error reporting by exception and by error code.
In addition to portable errors codes and conditions supported by the The category provides member functions such as `message`, which returns a text
`error_code.hpp` header, system-specific headers support the Cygwin, Linux, message for a specific error value, and `equivalent`, which can be used to test
and Windows platforms. These headers are effectively no-ops if included for whether a specific error value correspond to an error condition such as "access
platforms other than their intended target. denied". `error_code` uses these category-provided functions in the
implementation of its `message` and `operator==` member functions.
Boost.System is part of the {cpp}11 Standard Library. Boost.System contains two predefined category classes, the generic category
A number of changes, particularly to names, were made by the C++ committee (a reference to which is returned by `generic_category()`) and the system
during standardization. The Boost implementation has been tracking those changes. category (`system_category()`). The generic category represents the error
See <<#ref_deprecated_names,Deprecated Names>> for synonyms provided to prevent values of the portable subset of `errno` values defined by the POSIX standard,
breakage of existing user code. whereas the system category is OS dependent. Under POSIX, the system category
represents the `errno` values returned by the OS APIs (a superset of those in
the generic category), whereas under Windows, the system category represents
the error values returned by `GetLastError()`.
The framework is extensible. Users can define their own categories by
deriving a class from `error_category` and implementing a function that
returns a reference to an instance of it. This capability is useful both for
describing library-defined error values, and for adapting existing C API
libraries that return integer error values.
For those who prefer error reporting via exceptions, Boost.System provides
a standard exception class `system_error` that stores an `error_code`.
Boost.System was standardized in {cpp}11 as `<system_error>`. For a while,
the two were equivalent, but Boost.System has evolved since then and now
contains a number of extensions over its standard sibling:
* A non-allocating overload of `message`;
* Support for nonzero error codes meaning success, via the `failed` member
functions;
* Support for 64 bit category identifiers, as a solution to the problem
that sometimes it's not possible to ensure that only one instance of a
category exists in the program;
* Support for attaching source locations (file/line/function) to error codes;
* A class `result<T>` that can be used to return either a value or an error
code from a function;
* Various other minor improvements.
`boost::system::error_code` can be converted to, and constructed from,
`std::error_code`.