22 KiB
[support.exception]
17 Language support library [support]
17.9 Exception handling [support.exception]
17.9.1 General [support.exception.general]
The header defines several types and functions related to the handling of exceptions in a C++ program.
17.9.2 Header synopsis [exception.syn]
// all freestandingnamespace std {class exception; class bad_exception; class nested_exception; using terminate_handler = void ()(); terminate_handler get_terminate() noexcept; terminate_handler set_terminate(terminate_handler f) noexcept; noreturn void terminate() noexcept; constexpr int uncaught_exceptions() noexcept; using exception_ptr = unspecified; constexpr exception_ptr current_exception() noexcept; noreturn constexpr void rethrow_exception(exception_ptr p); template constexpr exception_ptr make_exception_ptr(E e) noexcept; template constexpr const E exception_ptr_cast(const exception_ptr& p) noexcept; template void exception_ptr_cast(const exception_ptr&&) = delete; template noreturn constexpr void throw_with_nested(T&& t); template constexpr void rethrow_if_nested(const E& e);}
17.9.3 Class exception [exception]
namespace std {class exception {public:constexpr exception() noexcept; constexpr exception(const exception&) noexcept; constexpr exception& operator=(const exception&) noexcept; constexpr virtual ~exception(); constexpr virtual const char* what() const noexcept; };}
The classexception defines the base class for the types of objects thrown as exceptions by C++ standard library components, and certain expressions, to report errors detected during program execution.
Except where explicitly specified otherwise, each standard library class T that derives from class exception has the following publicly accessible member functions, each of them having a non-throwing exception specification ([except.spec]):
default constructor (unless the class synopsis shows other constructors)
copy constructor
copy assignment operator
The copy constructor and the copy assignment operator meet the following postcondition: If two objects lhs and rhs both have dynamic type T and lhs is a copy of rhs, thenstrcmp(lhs.what(), rhs.what()) is equal to 0.
The what() member function of each such T satisfies the constraints specified for exception::what() (see below).
constexpr exception(const exception& rhs) noexcept; constexpr exception& operator=(const exception& rhs) noexcept;
Postconditions: If *this and rhs both have dynamic type exception then the value of the expression strcmp(what(), rhs.what()) shall equal 0.
constexpr virtual ~exception();
Effects: Destroys an object of classexception.
constexpr virtual const char* what() const noexcept;
Returns: An implementation-defined ntbs, which during constant evaluation is encoded with the ordinary literal encoding ([lex.ccon]).
Remarks: The message may be anull-terminated multibyte string, suitable for conversion and display as awstring ([string.classes], [locale.codecvt]).
The return value remains valid until the exception object from which it is obtained is destroyed or a non-const member function of the exception object is called.
17.9.4 Class bad_exception [bad.exception]
namespace std {class bad_exception : public exception {public:// see [exception] for the specification of the special member functionsconstexpr const char* what() const noexcept override; };}
The classbad_exception defines the type of the object referenced by the exception_ptr returned from a call to current_exception ([propagation]) when the currently active exception object fails to copy.
constexpr const char* what() const noexcept override;
Returns: An implementation-defined ntbs.
17.9.5 Abnormal termination [exception.terminate]
17.9.5.1 Type terminate_handler [terminate.handler]
using terminate_handler = void (*)();
The type of a handler function to be invoked by terminatewhen terminating exception processing.
Required behavior: A terminate_handler shall terminate execution of the program without returning to the caller.
Default behavior: The implementation's default terminate_handler callsabort().
17.9.5.2 set_terminate [set.terminate]
terminate_handler set_terminate(terminate_handler f) noexcept;
Effects: Establishes the function designated by f as the current handler function for terminating exception processing.
Returns: The previous terminate_handler.
Remarks: It is unspecified whether a null pointer value designates the defaultterminate_handler.
17.9.5.3 get_terminate [get.terminate]
terminate_handler get_terminate() noexcept;
Returns: The current terminate_handler.
[Note 1:
This can be a null pointer value.
â end note]
17.9.5.4 terminate [terminate]
[[noreturn]] void terminate() noexcept;
Effects: Calls a terminate_handler function.
It is unspecified whichterminate_handler function will be called if an exception is active during a call to set_terminate.
Otherwise calls the current terminate_handler function.
[Note 1:
A default terminate_handler is always considered a callable handler in this context.
â end note]
Remarks: Called by the implementation when exception handling must be abandoned for any of several reasons ([except.terminate]).
May also be called directly by the program.
17.9.6 uncaught_exceptions [uncaught.exceptions]
constexpr int uncaught_exceptions() noexcept;
Returns: The number of uncaught exceptions ([except.throw]) in the current thread.
Remarks: When uncaught_exceptions() > 0, throwing an exception can result in a call of the functionstd::terminate.
17.9.7 Exception propagation [propagation]
using exception_ptr = unspecified;
The type exception_ptr can be used to refer to an exception object.
exception_ptr meets the requirements ofCpp17NullablePointer (Table 36).
Two non-null values of type exception_ptr are equivalent and compare equal if and only if they refer to the same exception.
The default constructor of exception_ptr produces the null value of the type.
exception_ptr shall not be implicitly convertible to any arithmetic, enumeration, or pointer type.
[Note 1:
An implementation can use a reference-counted smart pointer as exception_ptr.
â end note]
For purposes of determining the presence of a data race, operations onexception_ptr objects shall access and modify only theexception_ptr objects themselves and not the exceptions they refer to.
Use of rethrow_exception or exception_ptr_cast on exception_ptr objects that refer to the same exception object shall not introduce a data race.
[Note 2:
Ifrethrow_exception rethrows the same exception object (rather than a copy), concurrent access to that rethrown exception object can introduce a data race.
Changes in the number of exception_ptr objects that refer to a particular exception do not introduce a data race.
â end note]
All member functions are marked constexpr.
constexpr exception_ptr current_exception() noexcept;
Returns: An exception_ptr object that refers to thecurrently handled exception or a copy of the currently handled exception, or a null exception_ptr object if no exception is being handled.
The referenced object shall remain valid at least as long as there is anexception_ptr object that refers to it.
If the function needs to allocate memory and the attempt fails, it returns anexception_ptr object that refers to an instance of bad_alloc.
It is unspecified whether the return values of two successive calls tocurrent_exception refer to the same exception object.
[Note 3:
That is, it is unspecified whether current_exception creates a new copy each time it is called.
â end note]
If the attempt to copy the current exception object throws an exception, the function returns an exception_ptr object that refers to the thrown exception or, if this is not possible, to an instance of bad_exception.
[Note 4:
The copy constructor of the thrown exception can also fail, so the implementation can substitute a bad_exception object to avoid infinite recursion.
â end note]
[[noreturn]] constexpr void rethrow_exception(exception_ptr p);
Preconditions: p is not a null pointer.
Effects: Let u be the exception object to which p refers, or a copy of that exception object.
It is unspecified whether a copy is made, and memory for the copy is allocated in an unspecified way.
If allocating memory to form u fails, throws an instance of bad_alloc;
otherwise, if copying the exception to which p refers to form u throws an exception, throws that exception;
otherwise, throws u.
template<class E> constexpr exception_ptr make_exception_ptr(E e) noexcept;
Effects: Creates an exception_ptr object that refers to a copy of e, as if:try {throw e;} catch(...) {return current_exception();}
[Note 5:
This function is provided for convenience and efficiency reasons.
â end note]
template<class E> constexpr const E* exception_ptr_cast(const exception_ptr& p) noexcept;
Mandates: E is a cv-unqualified complete object type.
E is not an array type.
E is not a pointer or pointer-to-member type.
[Note 6:
When E is a pointer or pointer-to-member type, a handler of type const E& can match without binding to the exception object itself.
â end note]
Returns: A pointer to the exception object referred to by p, if p is not null and a handler of type const E& would be a match ([except.handle]) for that exception object.
Otherwise, nullptr.
17.9.8 nested_exception [except.nested]
namespace std {class nested_exception {public:constexpr nested_exception() noexcept; constexpr nested_exception(const nested_exception&) noexcept = default; constexpr nested_exception& operator=(const nested_exception&) noexcept = default; constexpr virtual ~nested_exception() = default; // access functionsnoreturn constexpr void rethrow_nested() const; constexpr exception_ptr nested_ptr() const noexcept; }; template noreturn constexpr void throw_with_nested(T&& t); template constexpr void rethrow_if_nested(const E& e);}
The class nested_exception is designed for use as a mixin through multiple inheritance.
It captures the currently handled exception and stores it for later use.
[Note 1:
nested_exception has a virtual destructor to make it a polymorphic class.
Its presence can be tested for with dynamic_cast.
â end note]
constexpr nested_exception() noexcept;
Effects: The constructor calls current_exception() and stores the returned value.
[[noreturn]] constexpr void rethrow_nested() const;
Effects: If nested_ptr() returns a null pointer, the function calls the function std::terminate.
Otherwise, it throws the stored exception captured by *this.
constexpr exception_ptr nested_ptr() const noexcept;
Returns: The stored exception captured by this nested_exception object.
template<class T> [[noreturn]] constexpr void throw_with_nested(T&& t);
Let U be decay_t.
Preconditions: U meets the Cpp17CopyConstructible requirements.
Throws: If is_class_v && !is_final_v && !is_base_of_v<nested_exception, U> is true, an exception of unspecified type that is publicly derived from bothU and nested_exception and constructed from std::forward(t), otherwisestd::forward(t).
template<class E> constexpr void rethrow_if_nested(const E& e);
Effects: If E is not a polymorphic class type, or if nested_exception is an inaccessible or ambiguous base class of E, there is no effect.
Otherwise, performs:if (auto p = dynamic_cast<const nested_exception*>(addressof(e))) p->rethrow_nested();