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

Merge branch 'develop' into feature/error-condition

Browse Source
This commit is contained in:
Peter Dimov
2021-06-13 07:12:16 +03:00
parent f8ab3df822 1caaacff57
commit b74b1e3c8c
3 changed files with 322 additions and 174 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
doc/system.adoc
View File

@ -10,7 +10,7 @@ http://www.boost.org/LICENSE_1_0.txt
# Boost.System: Extensible Error Reporting
Beman Dawes, Christopher Kohlhoff, Peter Dimov
:toc: left
:toclevels: 3
:toclevels: 4
:idprefix:
:docinfo: private-footer

4
doc/system/copyright.adoc
View File

@ -1,5 +1,5 @@
////
Copyright 2018 Peter Dimov
Copyright 2018-2021 Peter Dimov
Distributed under the Boost Software License, Version 1.0.
@ -14,6 +14,6 @@ http://www.boost.org/LICENSE_1_0.txt
This documentation is
* Copyright 2003-2017 Beman Dawes
* Copyright 2018 Peter Dimov
* Copyright 2018-2021 Peter Dimov
and is distributed under the http://www.boost.org/LICENSE_1_0.txt[Boost Software License, Version 1.0].

490
doc/system/reference.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.
@ -48,31 +48,53 @@ the old names, but will provide them when the macro `BOOST_SYSTEM_ENABLE_DEPRECA
|`native_ecat`|`system_category()`
|===
## <boost/system/error_code.hpp>
## <boost/system/{zwsp}is_error_code_enum.hpp>
### Synopsis
### is_error_code_enum
```
namespace boost {
namespace system {
class error_category;
constexpr const error_category & system_category() noexcept;
constexpr const error_category & generic_category() noexcept;
class error_code;
class error_condition;
// "Concept" helpers
template<class T>
struct is_error_code_enum { static const bool value = false; };
} // namespace system
} // namespace boost
```
Users may specialize `is_error_code_enum` for their error enumeration
types to indicate that they should be eligible for automatic conversions
to `error_code`. This conversion calls `make_error_code(e)`, which should
be provided in the same namespace as the enumeration type.
## <boost/system/{zwsp}is_error_condition_enum.hpp>
### is_error_condition_enum
```
namespace boost {
namespace system {
template<class T>
struct is_error_condition_enum { static const bool value = false; };
// generic error conditions
} // namespace system
} // namespace boost
```
Users may specialize `is_error_condition_enum` for their error enumeration
types to indicate that they should be eligible for automatic conversions
to `error_condition`. This conversion calls `make_error_condition(e)`, which
should be provided in the same namespace as the enumeration type.
## <boost/system/{zwsp}errc.hpp>
### errc
```
namespace boost {
namespace system {
namespace errc {
enum errc_t
@ -163,52 +185,80 @@ namespace boost {
template<> struct is_error_condition_enum<errc::errc_t>
{ static const bool value = true; };
// non-member functions
constexpr bool operator==( const error_code & lhs,
const error_code & rhs ) noexcept;
bool operator==( const error_code & code,
const error_condition & condition ) noexcept;
bool operator==( const error_condition & condition,
const error_code & code ) noexcept;
constexpr bool operator==( const error_condition & lhs,
const error_condition & rhs ) noexcept;
constexpr bool operator!=( const error_code & lhs,
const error_code & rhs ) noexcept;
bool operator!=( const error_code & code,
const error_condition & condition ) noexcept;
bool operator!=( const error_condition & condition,
const error_code & code ) noexcept;
constexpr bool operator!=( const error_condition & lhs,
const error_condition & rhs ) noexcept;
constexpr bool operator<( const error_code & lhs,
const error_code & rhs ) noexcept;
constexpr bool operator<( const error_condition & lhs,
const error_condition & rhs ) noexcept;
constexpr error_code make_error_code( errc::errc_t e ) noexcept;
constexpr error_condition make_error_condition( errc::errc_t e ) noexcept;
template <class charT, class traits>
std::basic_ostream<charT, traits>&
operator<<( basic_ostream<charT, traits>& os, const error_code & ec );
std::size_t hash_value( const error_code & ec );
} // namespace system
} // namespace boost
```
The value of each `errc_t` constant is the same as the value of the `<cerrno>`
macro shown in the above synopsis.
The predefined enumeration type `errc::errc_t` provides named constants
corresponding to the values of the `<cerrno>` macros.
Users may specialize `is_error_code_enum` and `is_error_condition_enum`
templates to indicate that a type is eligible for class `error_code` and
`error_condition` automatic conversions respectively.
```
constexpr error_condition make_error_condition( errc::errc_t e ) noexcept;
```
[none]
* {blank}
+
Returns: :: `error_condition( e, generic_category() )`.
### Class error_category
Since `errc::errc_t` provides a specialization of `is_error_condition_enum`
and an overload of `make_error_condition`, it can be converted implicitly to
an `error_condition`. This is typically useful when comparing `error_code`
values returned from APIs to a portable condition, as in the below example:
* {blank}
+
```
void api_function( boost::system::error_code& ec );
void my_function()
{
boost::system::error_code ec;
api_function( ec );
if( ec == boost::system::errc::no_such_file_or_directory )
{
// an entity wasn't found (ENOENT)
// handle this condition
}
}
```
```
constexpr error_code make_error_code( errc::errc_t e ) noexcept;
```
[none]
* {blank}
+
Returns: :: `error_code( e, generic_category() )`.
In addition to `make_error_condition`, `errc::errc_t` provides an overload of
`make_error_code`. This allows the creation of generic error codes, an
operation typically useful when a function needs to signal a generic failure
that does not come from an underlying API, such as for instance an out of
memory condition:
* {blank}
+
```
void my_api_function( boost::system::error_code& ec )
{
void* p = std::malloc( 16 );
if( p == 0 )
{
// return ENOMEM
ec = make_error_code( boost::system::errc::out_of_memory );
return;
}
// use p
}
```
## <boost/system/{zwsp}error_category.hpp>
### error_category
The class `error_category` defines the base class for types used
to identify the source and encoding of a particular category of error code.
@ -251,9 +301,13 @@ namespace boost {
virtual bool failed( int ev ) const noexcept;
constexpr bool operator==( const error_category & rhs ) const noexcept;
constexpr bool operator!=( const error_category & rhs ) const noexcept;
constexpr bool operator< ( const error_category & rhs ) const noexcept;
friend constexpr bool operator==( const error_category & lhs,
const error_category & rhs ) noexcept;
friend constexpr bool operator!=( const error_category & lhs,
const error_category & rhs ) noexcept;
friend constexpr bool operator< ( const error_category & lhs,
const error_category & rhs ) noexcept;
operator std::error_category const & () const;
@ -397,37 +451,42 @@ Returns: ::
Remarks: ::
All calls to this function with the same `ev` must return the same value.
#### Nonvirtuals
#### Comparisons
```
constexpr bool operator==( const error_category & rhs ) const noexcept;
friend constexpr bool operator==( const error_category & lhs,
const error_category & rhs ) noexcept;
```
[none]
* {blank}
+
Returns: :: `rhs.id_ == 0? this == &rhs: id_ == rhs.id_`.
Remarks: :: Two category objects are considered equivalent when they have matching
nonzero identifiers, or are the same object.
Returns: :: `rhs.id_ == 0? &lhs == &rhs: lhs.id_ == rhs.id_`.
Remarks: :: Two category objects are considered equivalent when they have
matching nonzero identifiers, or are the same object.
```
constexpr bool operator!=( const error_category & rhs ) const noexcept;
friend constexpr bool operator!=( const error_category & lhs,
const error_category & rhs ) noexcept;
```
[none]
* {blank}
+
Returns: :: `!( *this == rhs )`.
Returns: :: `!( lhs == rhs )`.
```
constexpr bool operator< ( const error_category & rhs ) const noexcept;
constexpr bool operator< ( const error_category & lhs,
const error_category & rhs ) const noexcept;
```
[none]
* {blank}
+
Returns: ::
** If `id_ < rhs.id_`, `true`;
** Otherwise, if `id_ > rhs.id_`, `false`;
** If `lhs.id_ < rhs.id_`, `true`;
** Otherwise, if `lhs.id_ > rhs.id_`, `false`;
** Otherwise, if `rhs.id_ != 0`, `false`;
** Otherwise, `std::less<error_category const *>()( this, &rhs )`.
** Otherwise, `std::less<error_category const *>()( &lhs, &rhs )`.
#### Conversions
```
operator std::error_category const & () const;
@ -438,7 +497,19 @@ operator std::error_category const & () const;
Returns: :: A reference to an `std::error_category` object corresponding
to `*this`.
### Predefined Categories
## <boost/system/{zwsp}system_category.hpp>
### system_category
```
namespace boost {
namespace system {
constexpr const error_category & system_category() noexcept;
} // namespace system
} // namespace boost
```
```
constexpr const error_category & system_category() noexcept;
@ -446,8 +517,22 @@ constexpr const error_category & system_category() noexcept;
[none]
* {blank}
+
Returns: :: A reference to an `error_category` object identifying errors
originating from the operating system.
Returns: :: A reference to a predefined `error_category` object identifying
errors originating from the operating system.
## <boost/system/{zwsp}generic_category.hpp>
### generic_category
```
namespace boost {
namespace system {
constexpr const error_category & generic_category() noexcept;
} // namespace system
} // namespace boost
```
```
constexpr const error_category & generic_category() noexcept;
@ -455,10 +540,12 @@ constexpr const error_category & generic_category() noexcept;
[none]
* {blank}
+
Returns: :: A reference to an `error_category` object identifying portable
error conditions.
Returns: :: A reference to a predefined `error_category` object identifying
portable error codes and conditions.
### Class error_code
## <boost/system/{zwsp}error_code.hpp>
### error_code
The class `error_code` describes an object used to hold error code
values, such as those originating from the operating system or other
@ -502,14 +589,39 @@ namespace boost {
constexpr bool failed() const noexcept;
constexpr explicit operator bool() const noexcept;
// comparisons:
friend constexpr bool operator==( const error_code & lhs,
const error_code & rhs ) noexcept;
friend constexpr bool operator!=( const error_code & lhs,
const error_code & rhs ) noexcept;
friend constexpr bool operator<( const error_code & lhs,
const error_code & rhs ) noexcept;
// conversions:
operator std::error_code() const;
private: // exposition only
int val_;
const error_category * cat_;
};
// non-member functions
bool operator==( const error_code & code,
const error_condition & condition ) noexcept;
bool operator==( const error_condition & condition,
const error_code & code ) noexcept;
bool operator!=( const error_code & code,
const error_condition & condition ) noexcept;
bool operator!=( const error_condition & condition,
const error_code & code ) noexcept;
template <class charT, class traits>
std::basic_ostream<charT, traits>&
operator<<( basic_ostream<charT, traits>& os, const error_code & ec );
std::size_t hash_value( const error_code & ec );
}
}
```
@ -522,7 +634,7 @@ constexpr error_code() noexcept;
[none]
* {blank}
+
Ensures: :: `val_ == 0`; `*cat_ == system_category()`.
Ensures: :: `value() == 0`; `category() == system_category()`.
```
constexpr error_code( int val, const error_category & cat ) noexcept;
@ -530,7 +642,7 @@ constexpr error_code( int val, const error_category & cat ) noexcept;
[none]
* {blank}
+
Ensures: :: `val_ == val`; `cat_ == &cat`.
Ensures: :: `value() == val`; `category() == cat`.
```
template <class ErrorCodeEnum>
@ -550,7 +662,7 @@ constexpr void assign( int val, const error_category & cat ) noexcept;
[none]
* {blank}
+
Ensures: :: `val_ == val`; `cat_ == &cat`.
Ensures: :: `value() == val`; `category() == cat`.
```
template<typename ErrorCodeEnum>
@ -569,7 +681,7 @@ constexpr void clear() noexcept;
* {blank}
+
Ensures: ::
`val_ == 0`; `*cat_ == system_category()`.
`value() == 0`; `category() == system_category()`.
#### Observers
@ -579,7 +691,7 @@ constexpr int value() const noexcept;
[none]
* {blank}
+
Returns: :: `val_`.
Returns: :: the error value.
```
constexpr const error_category & category() const noexcept;
@ -587,7 +699,7 @@ constexpr const error_category & category() const noexcept;
[none]
* {blank}
+
Returns: :: `*cat_`.
Returns: :: the error category.
```
error_condition default_error_condition() const noexcept;
@ -595,7 +707,7 @@ error_condition default_error_condition() const noexcept;
[none]
* {blank}
+
Returns: :: `cat_\->default_error_condition( val_ )`.
Returns: :: `category().default_error_condition( value() )`.
```
std::string message() const;
@ -603,7 +715,7 @@ std::string message() const;
[none]
* {blank}
+
Returns: :: `cat_\->message( val_ )`.
Returns: :: `category().message( value() )`.
```
char const * message( char * buffer, std::size_t len ) const noexcept;
@ -611,7 +723,7 @@ char const * message( char * buffer, std::size_t len ) const noexcept;
[none]
* {blank}
+
Returns: :: `cat_\->message( val_, buffer, len )`.
Returns: :: `category().message( value(), buffer, len )`.
```
constexpr bool failed() const noexcept;
@ -619,7 +731,7 @@ constexpr bool failed() const noexcept;
[none]
* {blank}
+
Returns: :: `cat_\->failed( val_ )`.
Returns: :: `category().failed( value() )`.
```
constexpr explicit operator bool() const noexcept;
@ -627,7 +739,40 @@ constexpr explicit operator bool() const noexcept;
[none]
* {blank}
+
Returns: :: `failed()`.
Returns: ::
`failed()`.
#### Comparisons
```
friend constexpr bool operator==( const error_code & lhs,
const error_code & rhs ) noexcept;
```
[none]
* {blank}
+
Returns: :: `lhs.value() == rhs.value() && lhs.category() == rhs.category()`.
```
friend constexpr bool operator!=( const error_code & lhs,
const error_code & rhs ) noexcept;
```
[none]
* {blank}
+
Returns: :: `!( lhs == rhs )`.
```
friend constexpr bool operator<( const error_code & lhs,
const error_code & rhs ) noexcept;
```
[none]
* {blank}
+
Returns: ::
`lhs.category() < rhs.category() || (lhs.category() == rhs.category() && lhs.value() < rhs.value())`.
#### Conversions
```
operator std::error_code() const;
@ -636,9 +781,55 @@ operator std::error_code() const;
* {blank}
+
Returns: ::
`std::error_code( val_, *cat_ )`.
`std::error_code( value(), category() )`.
### Class error_condition
#### Nonmembers
```
bool operator==( const error_code & code,
const error_condition & condition ) noexcept;
bool operator==( const error_condition & condition,
const error_code & code ) noexcept;
```
[none]
* {blank}
+
Returns: :: `code.category().equivalent(code.value(), condition) || condition.category().equivalent(code, condition.value())`.
```
bool operator!=( const error_code & code,
const error_condition & condition ) noexcept;
bool operator!=( const error_condition & condition,
const error_code & code ) noexcept;
```
[none]
* {blank}
+
Returns: :: `!( lhs == rhs )`.
```
template <class charT, class traits>
std::basic_ostream<charT, traits>&
operator<<( basic_ostream<charT, traits>& os, const error_code & ec );
```
[none]
* {blank}
+
Effects: :: `os << ec.category().name() << ':' << ec.value()`.
Returns: :: `os`.
```
std::size_t hash_value( const error_code & ec );
```
[none]
* {blank}
+
Returns: ::
A hash value representing `ec`.
## <boost/system/{zwsp}error_condition.hpp>
### error_condition
```
namespace boost {
@ -675,13 +866,19 @@ namespace boost {
constexpr bool failed() const noexcept;
constexpr explicit operator bool() const noexcept;
// comparisons:
friend constexpr bool operator==( const error_condition & lhs,
const error_condition & rhs ) noexcept;
friend constexpr bool operator!=( const error_condition & lhs,
const error_condition & rhs ) noexcept;
friend constexpr bool operator<( const error_condition & lhs,
const error_condition & rhs ) noexcept;
// conversions:
operator std::error_condition() const;
private: // exposition only
int val_;
const error_category * cat_;
};
}
}
@ -695,7 +892,7 @@ constexpr error_condition() noexcept;
[none]
* {blank}
+
Ensures: :: `val_ == 0`; `*cat_ == generic_category()`.
Ensures: :: `value() == 0`; `category() == generic_category()`.
```
constexpr error_condition( int val, const error_category & cat ) noexcept;
@ -703,7 +900,7 @@ constexpr error_condition( int val, const error_category & cat ) noexcept;
[none]
* {blank}
+
Ensures: :: `val_ == val`; `cat_ == &cat`.
Ensures: :: `value() == val`; `category() == cat`.
```
template <class ErrorConditionEnum>
@ -724,7 +921,7 @@ constexpr void assign( int val, const error_category & cat ) noexcept;
[none]
* {blank}
+
Ensures: :: `val_ == val`; `cat_ == &cat`.
Ensures: :: `value() == val`; `category() == cat`.
```
template <class ErrorConditionEnum>
@ -743,7 +940,7 @@ constexpr void clear() noexcept;
* {blank}
+
Ensures: ::
`val_ == 0`; `*cat_ == generic_category()`.
`value() == 0`; `category() == generic_category()`.
#### Observers
@ -753,7 +950,7 @@ constexpr int value() const noexcept;
[none]
* {blank}
+
Returns: :: `val_`.
Returns: :: the error value.
```
constexpr const error_category & category() const noexcept;
@ -761,7 +958,7 @@ constexpr const error_category & category() const noexcept;
[none]
* {blank}
+
Returns: :: `*cat_`.
Returns: :: the error category.
```
std::string message() const;
@ -769,7 +966,7 @@ std::string message() const;
[none]
* {blank}
+
Returns: :: `cat_\->message( val_ )`.
Returns: :: `category().message( value() )`.
```
char const * message( char * buffer, std::size_t len ) const noexcept;
@ -777,7 +974,7 @@ char const * message( char * buffer, std::size_t len ) const noexcept;
[none]
* {blank}
+
Returns: :: `cat_\->message( val_, buffer, len )`.
Returns: :: `category().message( value(), buffer, len )`.
```
constexpr bool failed() const noexcept;
@ -785,7 +982,7 @@ constexpr bool failed() const noexcept;
[none]
* {blank}
+
Returns: :: `cat_\->failed( val_ )`.
Returns: :: `category().failed( value() )`.
```
constexpr explicit operator bool() const noexcept;
@ -793,23 +990,13 @@ constexpr explicit operator bool() const noexcept;
[none]
* {blank}
+
Returns: :: `failed()`.
```
operator std::error_condition() const;
```
[none]
* {blank}
+
Returns: ::
`std::error_condition( val_, *cat_ )`.
`failed()`.
### Nonmember functions
#### Comparisons
```
constexpr bool operator==( const error_code & lhs,
const error_code & rhs ) noexcept;
constexpr bool operator==( const error_condition & lhs,
friend constexpr bool operator==( const error_condition & lhs,
const error_condition & rhs ) noexcept;
```
[none]
@ -818,25 +1005,8 @@ constexpr bool operator==( const error_condition & lhs,
Returns: :: `lhs.value() == rhs.value() && lhs.category() == rhs.category()`.
```
bool operator==( const error_code & code,
const error_condition & condition ) noexcept;
bool operator==( const error_condition & condition,
const error_code & code ) noexcept;
```
[none]
* {blank}
+
Returns: :: `code.category().equivalent( code.value(), condition ) || condition.category().equivalent( code, condition.value() )`.
```
constexpr bool operator!=( const error_code & lhs,
const error_code & rhs ) noexcept;
constexpr bool operator!=( const error_condition & lhs,
friend constexpr bool operator!=( const error_condition & lhs,
const error_condition & rhs ) noexcept;
bool operator!=( const error_code & code,
const error_condition & condition ) noexcept;
bool operator!=( const error_condition & condition,
const error_code & code ) noexcept;
```
[none]
* {blank}
@ -844,53 +1014,27 @@ bool operator!=( const error_condition & condition,
Returns: :: `!( lhs == rhs )`.
```
constexpr bool operator<( const error_code & lhs,
const error_code & rhs ) noexcept;
constexpr bool operator<( const error_condition & lhs,
friend constexpr bool operator<( const error_condition & lhs,
const error_condition & rhs ) noexcept;
```
[none]
* {blank}
+
Returns: :: `lhs.category() < rhs.category() || ( lhs.category() == rhs.category() && lhs.value() < rhs.value() )`.
Returns: ::
`lhs.category() < rhs.category() || (lhs.category() == rhs.category() && lhs.value() < rhs.value())`.
#### Conversions
```
constexpr error_code make_error_code( errc::errc_t e ) noexcept;
```
[none]
* {blank}
+
Returns: :: `error_code( e, generic_category() )`.
```
constexpr error_condition make_error_condition( errc::errc_t e ) noexcept;
```
[none]
* {blank}
+
Returns: :: `error_condition( e, generic_category() )`.
```
template <class charT, class traits>
std::basic_ostream<charT, traits>&
operator<<( basic_ostream<charT, traits>& os, const error_code & ec );
```
[none]
* {blank}
+
Effects: :: `os << ec.category().name() << ':' << ec.value()`.
Returns: :: `os`.
```
std::size_t hash_value( const error_code & ec );
operator std::error_condition() const;
```
[none]
* {blank}
+
Returns: ::
A hash value representing `ec`.
`std::error_condition( value(), category() )`.
## <boost/system/system_error.hpp>
## <boost/system/{zwsp}system_error.hpp>
### Class system_error
@ -967,4 +1111,8 @@ const char * what() const noexcept;
* {blank}
+
Returns: :: A null-terminated character string incorporating the arguments supplied
in the constructor, typically of the form `what_arg + ": " + code.message()`.
in the constructor, typically of the form `what_arg + ": " + code().message()`.
## <boost/system.hpp>
This convenience header includes all the headers previously described.