[support.exception] (original) (raw)

17 Language support library [support]

17.9 Exception handling [support.exception]

The header <exception>defines several types and functions related to the handling of exceptions in a C++ program.

17.9.1 Header synopsis [exception.syn]

namespace 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;

int uncaught_exceptions() noexcept;

using exception_ptr = unspecified;

exception_ptr current_exception() noexcept; [[noreturn]] void rethrow_exception(exception_ptr p); template exception_ptr make_exception_ptr(E e) noexcept;

template [[noreturn]] void throw_with_nested(T&& t); template void rethrow_if_nested(const E& e); }

17.9.2 Class exception [exception]

namespace std { class exception { public: exception() noexcept; exception(const exception&) noexcept; exception& operator=(const exception&) noexcept; virtual ~exception(); virtual const char* what() const noexcept; }; }

The classexceptiondefines 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.

Each standard library class T that derives from class exceptionhas the following publicly accessible member functions, each of them having a non-throwing exception specification ([except.spec]):

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).

exception(const exception& rhs) noexcept; exception& operator=(const exception& rhs) noexcept;

Postconditions:If *this and rhs both have dynamic type exceptionthen the value of the expression strcmp(what(), rhs.what()) shall equal 0.

Effects:Destroys an object of classexception.

virtual const char* what() const noexcept;

Returns:An implementation-defined ntbs.

The return value remains valid until the exception object from which it is obtained is destroyed or a non-constmember function of the exception object is called.

17.9.3 Class bad_­exception [bad.exception]

namespace std { class bad_exception : public exception { public:

const char* what() const noexcept override;

}; }

The classbad_­exceptiondefines the type of the object referenced by the exception_­ptrreturned from a call to current_­exception ([propagation]) when the currently active exception object fails to copy.

const char* what() const noexcept override;

Returns:An implementation-defined ntbs.

17.9.4 Abnormal termination [exception.terminate]

17.9.4.1 Type terminate_­handler [terminate.handler]

using terminate_handler = void (*)();

The type of ahandler functionto be called bystd​::​terminate() when 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.4.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.

Remarks:It is unspecified whether a null pointer value designates the defaultterminate_­handler.

Returns:The previous terminate_­handler.

17.9.4.3 get_­terminate [get.terminate]

terminate_handler get_terminate() noexcept;

Returns:The current terminate_­handler.

[ Note

:

This may be a null pointer value.

— end note

]

17.9.4.4 terminate [terminate]

[[noreturn]] void terminate() noexcept;

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.

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

:

A default terminate_­handler is always considered a callable handler in this context.

— end note

]

17.9.5 uncaught_­exceptions [uncaught.exceptions]

int uncaught_exceptions() noexcept;

Remarks:When uncaught_­exceptions() > 0, throwing an exception can result in a call of the functionstd​::​terminate.

17.9.6 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 33).

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

:

An implementation might 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 on exception_­ptr objects that refer to the same exception object shall not introduce a data race.

[ Note

:

Ifrethrow_­exception rethrows the same exception object (rather than a copy), concurrent access to that rethrown exception object may 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

]

exception_ptr current_exception() noexcept;

Returns:An exception_­ptr object that refers to thecurrently handled exceptionor 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

:

That is, it is unspecified whether current_­exceptioncreates 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

:

The copy constructor of the thrown exception may also fail, so the implementation is allowed to substitute a bad_­exception object to avoid infinite recursion.

— end note

]

[[noreturn]] void rethrow_exception(exception_ptr p);

Preconditions: p is not a null pointer.

Throws:The exception object to which p refers.

template<class E> 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

:

This function is provided for convenience and efficiency reasons.

— end note

]

17.9.7 nested_­exception [except.nested]

namespace std { class nested_exception { public: nested_exception() noexcept; nested_exception(const nested_exception&) noexcept = default; nested_exception& operator=(const nested_exception&) noexcept = default; virtual ~nested_exception() = default;

[[noreturn]] void rethrow_nested() const;
exception_ptr nested_ptr() const noexcept;

};

template [[noreturn]] void throw_with_nested(T&& t); template 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

:

nested_­exception has a virtual destructor to make it a polymorphic class.

Its presence can be tested for with dynamic_­cast.

— end note

]

nested_exception() noexcept;

Effects:The constructor calls current_­exception() and stores the returned value.

[[noreturn]] 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.

exception_ptr nested_ptr() const noexcept;

Returns:The stored exception captured by this nested_­exception object.

template<class T> [[noreturn]] void throw_with_nested(T&& t);

Preconditions: U meets the Cpp17CopyConstructible requirements.

Throws:If is_­class_­v<U> && !is_­final_­v<U> && !is_­base_­of_­v<nested_­exception, U>is true, an exception of unspecified type that is publicly derived from bothU and nested_­exceptionand constructed from std​::​forward<T>(t), otherwisestd​::​forward<T>(t).

template<class E> 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();