boostorg/system
1
0
Fork 1
mirror of https://github.com/boostorg/system.git synced 2025-07-29 20:17:13 +02:00
Code Issues Packages Projects Releases Wiki 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 2018 Peter Dimov
Copyright 2018, 2021 Peter Dimov
Distributed under the Boost Software License, Version 1.0.
@ -12,39 +12,67 @@ http://www.boost.org/LICENSE_1_0.txt
# Introduction
:idprefix: intro_
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.
Errors originating from the operating system or other low-level application
program interfaces (APIs) are typically reported via an integer representing
an error code, either by returning the code directly from the function (e.g.
`pthread_mutex_init`) or by using a side channel such as the `errno`
pseudo-variable under POSIX or `GetLastError()` under Windows.
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`.
However, these integer error values can only be interpreted when their source
is known. The value 5 under Windows means `ERROR_ACCESS_DENIED` when returned
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
`std::runtime_error`, it captures the underlying `error_code` for the problem
causing the exception so that this important information is not lost.
This means that in order for code to be able to handle errors from both
sources (to retrieve a text message describing the error, or to check whether
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
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 inefficient. The Boost System library
supports both error reporting by exception and by error code.
Boost.System provides a framework in which this is possible. Errors are
represented by a class `error_code` which contains both the error value and
a pointer to their source (called "category"), represented as a class derived
from `error_category`.
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.
The category provides member functions such as `message`, which returns a text
message for a specific error value, and `equivalent`, which can be used to test
whether a specific error value correspond to an error condition such as "access
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.
A number of changes, particularly to names, were made by the C++ committee
during standardization. The Boost implementation has been tracking those changes.
See <<#ref_deprecated_names,Deprecated Names>> for synonyms provided to prevent
breakage of existing user code.
Boost.System contains two predefined category classes, the generic category
(a reference to which is returned by `generic_category()`) and the system
category (`system_category()`). The generic category represents the error
values of the portable subset of `errno` values defined by the POSIX standard,
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`.