Improve API docs for <system_error> header
* include/std/system_error (error_category, error_code) (error_condition): Improve docs. * libsupc++/exception: Add missing @addtogroup Doxygen command. * libsupc++/exception_ptr.h (exception_ptr): Link equality operators to class documentation. Suppress documentation for implementation details. * libsupc++/nested_exception.h (throw_with_nested, rethrow_if_nested): Suppress documentation for implementation details. From-SVN: r270873
This commit is contained in:
parent
fe6fb0d159
commit
2f7f1aca29
|
@ -1,5 +1,14 @@
|
||||||
2019-05-04 Jonathan Wakely <jwakely@redhat.com>
|
2019-05-04 Jonathan Wakely <jwakely@redhat.com>
|
||||||
|
|
||||||
|
* include/std/system_error (error_category, error_code)
|
||||||
|
(error_condition): Improve docs.
|
||||||
|
* libsupc++/exception: Add missing @addtogroup Doxygen command.
|
||||||
|
* libsupc++/exception_ptr.h (exception_ptr): Link equality operators
|
||||||
|
to class documentation. Suppress documentation for implementation
|
||||||
|
details.
|
||||||
|
* libsupc++/nested_exception.h (throw_with_nested, rethrow_if_nested):
|
||||||
|
Suppress documentation for implementation details.
|
||||||
|
|
||||||
* include/std/system_error (error_code): Remove friend declaration
|
* include/std/system_error (error_code): Remove friend declaration
|
||||||
for hash<error_code>.
|
for hash<error_code>.
|
||||||
(hash<error_code>::operator()): Use public member functions to access
|
(hash<error_code>::operator()): Use public member functions to access
|
||||||
|
|
|
@ -44,6 +44,10 @@ namespace std _GLIBCXX_VISIBILITY(default)
|
||||||
{
|
{
|
||||||
_GLIBCXX_BEGIN_NAMESPACE_VERSION
|
_GLIBCXX_BEGIN_NAMESPACE_VERSION
|
||||||
|
|
||||||
|
/** @addtogroup diagnostics
|
||||||
|
* @{
|
||||||
|
*/
|
||||||
|
|
||||||
class error_code;
|
class error_code;
|
||||||
class error_condition;
|
class error_condition;
|
||||||
class system_error;
|
class system_error;
|
||||||
|
@ -70,7 +74,15 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
|
||||||
#endif // C++17
|
#endif // C++17
|
||||||
inline namespace _V2 {
|
inline namespace _V2 {
|
||||||
|
|
||||||
/// error_category
|
/** Abstract base class for types defining a category of error codes.
|
||||||
|
*
|
||||||
|
* An error category defines a context that give meaning to the integer
|
||||||
|
* stored in an `error_code` or `error_category` object. For example,
|
||||||
|
* the standard `errno` constants such a `EINVAL` and `ENOMEM` are
|
||||||
|
* associated with the "generic" category and other OS-specific error
|
||||||
|
* numbers are associated with the "system" category, but a user-defined
|
||||||
|
* category might give different meanings to the same numerical values.
|
||||||
|
*/
|
||||||
class error_category
|
class error_category
|
||||||
{
|
{
|
||||||
public:
|
public:
|
||||||
|
@ -131,18 +143,31 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
|
||||||
};
|
};
|
||||||
|
|
||||||
// DR 890.
|
// DR 890.
|
||||||
_GLIBCXX_CONST const error_category& system_category() noexcept;
|
|
||||||
|
/// Error category for `errno` error codes.
|
||||||
_GLIBCXX_CONST const error_category& generic_category() noexcept;
|
_GLIBCXX_CONST const error_category& generic_category() noexcept;
|
||||||
|
|
||||||
|
/// Error category for other error codes defined by the OS.
|
||||||
|
_GLIBCXX_CONST const error_category& system_category() noexcept;
|
||||||
|
|
||||||
} // end inline namespace
|
} // end inline namespace
|
||||||
|
|
||||||
error_code make_error_code(errc) noexcept;
|
error_code make_error_code(errc) noexcept;
|
||||||
|
|
||||||
template<typename _Tp>
|
/** Class error_code
|
||||||
struct hash;
|
*
|
||||||
|
* This class is a value type storing an integer error number and a
|
||||||
/// error_code
|
* category that gives meaning to the error number. Typically this is done
|
||||||
// Implementation-specific error identification
|
* close the the point where the error happens, to capture the original
|
||||||
|
* error value.
|
||||||
|
*
|
||||||
|
* An `error_code` object can be used to store the original error value
|
||||||
|
* emitted by some subsystem, with a category relevant to the subsystem.
|
||||||
|
* For example, errors from POSIX library functions can be represented by
|
||||||
|
* an `errno` value and the "generic" category, but errors from an HTTP
|
||||||
|
* library might be represented by an HTTP response status code (e.g. 404)
|
||||||
|
* and a custom category defined by the library.
|
||||||
|
*/
|
||||||
struct error_code
|
struct error_code
|
||||||
{
|
{
|
||||||
error_code() noexcept
|
error_code() noexcept
|
||||||
|
@ -198,6 +223,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
|
||||||
};
|
};
|
||||||
|
|
||||||
// 19.4.2.6 non-member functions
|
// 19.4.2.6 non-member functions
|
||||||
|
|
||||||
|
/// @relates error_code @{
|
||||||
|
|
||||||
inline error_code
|
inline error_code
|
||||||
make_error_code(errc __e) noexcept
|
make_error_code(errc __e) noexcept
|
||||||
{ return error_code(static_cast<int>(__e), generic_category()); }
|
{ return error_code(static_cast<int>(__e), generic_category()); }
|
||||||
|
@ -215,10 +243,19 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
|
||||||
operator<<(basic_ostream<_CharT, _Traits>& __os, const error_code& __e)
|
operator<<(basic_ostream<_CharT, _Traits>& __os, const error_code& __e)
|
||||||
{ return (__os << __e.category().name() << ':' << __e.value()); }
|
{ return (__os << __e.category().name() << ':' << __e.value()); }
|
||||||
|
|
||||||
|
// @}
|
||||||
|
|
||||||
error_condition make_error_condition(errc) noexcept;
|
error_condition make_error_condition(errc) noexcept;
|
||||||
|
|
||||||
/// error_condition
|
/** Class error_condition
|
||||||
// Portable error identification
|
*
|
||||||
|
* This class represents error conditions that may be visible at an API
|
||||||
|
* boundary. Different `error_code` values that can occur within a library
|
||||||
|
* or module might map to the same `error_condition`.
|
||||||
|
*
|
||||||
|
* An `error_condition` represents something that the program can test for,
|
||||||
|
* and subsequently take appropriate action.
|
||||||
|
*/
|
||||||
struct error_condition
|
struct error_condition
|
||||||
{
|
{
|
||||||
error_condition() noexcept
|
error_condition() noexcept
|
||||||
|
@ -272,10 +309,15 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
|
||||||
};
|
};
|
||||||
|
|
||||||
// 19.4.3.6 non-member functions
|
// 19.4.3.6 non-member functions
|
||||||
|
|
||||||
|
/// Create an `error_condition` representing a standard `errc` condition.
|
||||||
|
/// @relates error_condition
|
||||||
inline error_condition
|
inline error_condition
|
||||||
make_error_condition(errc __e) noexcept
|
make_error_condition(errc __e) noexcept
|
||||||
{ return error_condition(static_cast<int>(__e), generic_category()); }
|
{ return error_condition(static_cast<int>(__e), generic_category()); }
|
||||||
|
|
||||||
|
/// Define an ordering for error_condition objects.
|
||||||
|
/// @relates error_condition
|
||||||
inline bool
|
inline bool
|
||||||
operator<(const error_condition& __lhs,
|
operator<(const error_condition& __lhs,
|
||||||
const error_condition& __rhs) noexcept
|
const error_condition& __rhs) noexcept
|
||||||
|
@ -286,11 +328,15 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
|
||||||
}
|
}
|
||||||
|
|
||||||
// 19.4.4 Comparison operators
|
// 19.4.4 Comparison operators
|
||||||
|
|
||||||
|
/// @relates error_code
|
||||||
inline bool
|
inline bool
|
||||||
operator==(const error_code& __lhs, const error_code& __rhs) noexcept
|
operator==(const error_code& __lhs, const error_code& __rhs) noexcept
|
||||||
{ return (__lhs.category() == __rhs.category()
|
{ return (__lhs.category() == __rhs.category()
|
||||||
&& __lhs.value() == __rhs.value()); }
|
&& __lhs.value() == __rhs.value()); }
|
||||||
|
|
||||||
|
/// @relates error_code
|
||||||
|
/// @relates error_condition
|
||||||
inline bool
|
inline bool
|
||||||
operator==(const error_code& __lhs, const error_condition& __rhs) noexcept
|
operator==(const error_code& __lhs, const error_condition& __rhs) noexcept
|
||||||
{
|
{
|
||||||
|
@ -298,6 +344,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
|
||||||
|| __rhs.category().equivalent(__lhs, __rhs.value()));
|
|| __rhs.category().equivalent(__lhs, __rhs.value()));
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// @relates error_code
|
||||||
|
/// @relates error_condition
|
||||||
inline bool
|
inline bool
|
||||||
operator==(const error_condition& __lhs, const error_code& __rhs) noexcept
|
operator==(const error_condition& __lhs, const error_code& __rhs) noexcept
|
||||||
{
|
{
|
||||||
|
@ -305,6 +353,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
|
||||||
|| __lhs.category().equivalent(__rhs, __lhs.value()));
|
|| __lhs.category().equivalent(__rhs, __lhs.value()));
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// @relates error_condition
|
||||||
inline bool
|
inline bool
|
||||||
operator==(const error_condition& __lhs,
|
operator==(const error_condition& __lhs,
|
||||||
const error_condition& __rhs) noexcept
|
const error_condition& __rhs) noexcept
|
||||||
|
@ -313,18 +362,24 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
|
||||||
&& __lhs.value() == __rhs.value());
|
&& __lhs.value() == __rhs.value());
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// @relates error_code
|
||||||
inline bool
|
inline bool
|
||||||
operator!=(const error_code& __lhs, const error_code& __rhs) noexcept
|
operator!=(const error_code& __lhs, const error_code& __rhs) noexcept
|
||||||
{ return !(__lhs == __rhs); }
|
{ return !(__lhs == __rhs); }
|
||||||
|
|
||||||
|
/// @relates error_code
|
||||||
|
/// @relates error_condition
|
||||||
inline bool
|
inline bool
|
||||||
operator!=(const error_code& __lhs, const error_condition& __rhs) noexcept
|
operator!=(const error_code& __lhs, const error_condition& __rhs) noexcept
|
||||||
{ return !(__lhs == __rhs); }
|
{ return !(__lhs == __rhs); }
|
||||||
|
|
||||||
|
/// @relates error_code
|
||||||
|
/// @relates error_condition
|
||||||
inline bool
|
inline bool
|
||||||
operator!=(const error_condition& __lhs, const error_code& __rhs) noexcept
|
operator!=(const error_condition& __lhs, const error_code& __rhs) noexcept
|
||||||
{ return !(__lhs == __rhs); }
|
{ return !(__lhs == __rhs); }
|
||||||
|
|
||||||
|
/// @relates error_condition
|
||||||
inline bool
|
inline bool
|
||||||
operator!=(const error_condition& __lhs,
|
operator!=(const error_condition& __lhs,
|
||||||
const error_condition& __rhs) noexcept
|
const error_condition& __rhs) noexcept
|
||||||
|
@ -332,9 +387,12 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
|
||||||
|
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* @brief Thrown to indicate error code of underlying system.
|
* @brief An exception type that includes an `error_code` value.
|
||||||
*
|
*
|
||||||
* @ingroup exceptions
|
* Typically used to report errors from the operating system and other
|
||||||
|
* low-level APIs.
|
||||||
|
*
|
||||||
|
* @ingroup exceptions
|
||||||
*/
|
*/
|
||||||
class system_error : public std::runtime_error
|
class system_error : public std::runtime_error
|
||||||
{
|
{
|
||||||
|
@ -385,6 +443,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
|
||||||
#ifndef _GLIBCXX_COMPATIBILITY_CXX0X
|
#ifndef _GLIBCXX_COMPATIBILITY_CXX0X
|
||||||
// DR 1182.
|
// DR 1182.
|
||||||
/// std::hash specialization for error_code.
|
/// std::hash specialization for error_code.
|
||||||
|
/// @relates error_code
|
||||||
template<>
|
template<>
|
||||||
struct hash<error_code>
|
struct hash<error_code>
|
||||||
: public __hash_base<size_t, error_code>
|
: public __hash_base<size_t, error_code>
|
||||||
|
@ -401,6 +460,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
|
||||||
#if __cplusplus >= 201703L
|
#if __cplusplus >= 201703L
|
||||||
// DR 2686.
|
// DR 2686.
|
||||||
/// std::hash specialization for error_condition.
|
/// std::hash specialization for error_condition.
|
||||||
|
/// @relates error_condition
|
||||||
template<>
|
template<>
|
||||||
struct hash<error_condition>
|
struct hash<error_condition>
|
||||||
: public __hash_base<size_t, error_condition>
|
: public __hash_base<size_t, error_condition>
|
||||||
|
|
|
@ -41,6 +41,10 @@ extern "C++" {
|
||||||
|
|
||||||
namespace std
|
namespace std
|
||||||
{
|
{
|
||||||
|
/** @addtogroup exceptions
|
||||||
|
* @{
|
||||||
|
*/
|
||||||
|
|
||||||
/** If an %exception is thrown which is not listed in a function's
|
/** If an %exception is thrown which is not listed in a function's
|
||||||
* %exception specification, one of these may be thrown. */
|
* %exception specification, one of these may be thrown. */
|
||||||
class bad_exception : public exception
|
class bad_exception : public exception
|
||||||
|
|
|
@ -49,6 +49,7 @@ namespace std
|
||||||
* @addtogroup exceptions
|
* @addtogroup exceptions
|
||||||
* @{
|
* @{
|
||||||
*/
|
*/
|
||||||
|
|
||||||
namespace __exception_ptr
|
namespace __exception_ptr
|
||||||
{
|
{
|
||||||
class exception_ptr;
|
class exception_ptr;
|
||||||
|
@ -154,6 +155,8 @@ namespace std
|
||||||
__attribute__ ((__pure__));
|
__attribute__ ((__pure__));
|
||||||
};
|
};
|
||||||
|
|
||||||
|
/// @relates exception_ptr @{
|
||||||
|
|
||||||
bool
|
bool
|
||||||
operator==(const exception_ptr&, const exception_ptr&)
|
operator==(const exception_ptr&, const exception_ptr&)
|
||||||
_GLIBCXX_USE_NOEXCEPT __attribute__ ((__pure__));
|
_GLIBCXX_USE_NOEXCEPT __attribute__ ((__pure__));
|
||||||
|
@ -166,10 +169,14 @@ namespace std
|
||||||
swap(exception_ptr& __lhs, exception_ptr& __rhs)
|
swap(exception_ptr& __lhs, exception_ptr& __rhs)
|
||||||
{ __lhs.swap(__rhs); }
|
{ __lhs.swap(__rhs); }
|
||||||
|
|
||||||
|
// @}
|
||||||
|
|
||||||
|
/// @cond undocumented
|
||||||
template<typename _Ex>
|
template<typename _Ex>
|
||||||
inline void
|
inline void
|
||||||
__dest_thunk(void* __x)
|
__dest_thunk(void* __x)
|
||||||
{ static_cast<_Ex*>(__x)->~_Ex(); }
|
{ static_cast<_Ex*>(__x)->~_Ex(); }
|
||||||
|
/// @endcond
|
||||||
|
|
||||||
} // namespace __exception_ptr
|
} // namespace __exception_ptr
|
||||||
|
|
||||||
|
|
|
@ -76,6 +76,8 @@ namespace std
|
||||||
{ return _M_ptr; }
|
{ return _M_ptr; }
|
||||||
};
|
};
|
||||||
|
|
||||||
|
/// @cond undocumented
|
||||||
|
|
||||||
template<typename _Except>
|
template<typename _Except>
|
||||||
struct _Nested_exception : public _Except, public nested_exception
|
struct _Nested_exception : public _Except, public nested_exception
|
||||||
{
|
{
|
||||||
|
@ -106,6 +108,8 @@ namespace std
|
||||||
__throw_with_nested_impl(_Tp&& __t, false_type)
|
__throw_with_nested_impl(_Tp&& __t, false_type)
|
||||||
{ throw std::forward<_Tp>(__t); }
|
{ throw std::forward<_Tp>(__t); }
|
||||||
|
|
||||||
|
/// @endcond
|
||||||
|
|
||||||
/// If @p __t is derived from nested_exception, throws @p __t.
|
/// If @p __t is derived from nested_exception, throws @p __t.
|
||||||
/// Else, throws an implementation-defined object derived from both.
|
/// Else, throws an implementation-defined object derived from both.
|
||||||
template<typename _Tp>
|
template<typename _Tp>
|
||||||
|
@ -123,6 +127,8 @@ namespace std
|
||||||
std::__throw_with_nested_impl(std::forward<_Tp>(__t), __nest{});
|
std::__throw_with_nested_impl(std::forward<_Tp>(__t), __nest{});
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// @cond undocumented
|
||||||
|
|
||||||
// Determine if dynamic_cast<const nested_exception&> would be well-formed.
|
// Determine if dynamic_cast<const nested_exception&> would be well-formed.
|
||||||
template<typename _Tp>
|
template<typename _Tp>
|
||||||
using __rethrow_if_nested_cond = typename enable_if<
|
using __rethrow_if_nested_cond = typename enable_if<
|
||||||
|
@ -145,6 +151,8 @@ namespace std
|
||||||
__rethrow_if_nested_impl(const void*)
|
__rethrow_if_nested_impl(const void*)
|
||||||
{ }
|
{ }
|
||||||
|
|
||||||
|
/// @endcond
|
||||||
|
|
||||||
/// If @p __ex is derived from nested_exception, @p __ex.rethrow_nested().
|
/// If @p __ex is derived from nested_exception, @p __ex.rethrow_nested().
|
||||||
template<typename _Ex>
|
template<typename _Ex>
|
||||||
inline void
|
inline void
|
||||||
|
|
Loading…
Reference in New Issue