cppdraft_translate/cppdraft/propagation.md

[propagation]

17 Language support library [support]

17.9 Exception handling [support.exception]

17.9.7 Exception propagation [propagation]

🔗

using exception_ptr = unspecified;

1

#

The type exception_ptr can be used to refer to an exception object.

2

#

exception_ptr meets the requirements ofCpp17NullablePointer (Table 36).

3

#

Two non-null values of type exception_ptr are equivalent and compare equal if and only if they refer to the same exception.

4

#

The default constructor of exception_ptr produces the null value of the type.

5

#

exception_ptr shall not be implicitly convertible to any arithmetic, enumeration, or pointer type.

6

#

[Note 1:

An implementation can use a reference-counted smart pointer as exception_ptr.

— end note]

7

#

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]

8

#

All member functions are marked constexpr.

🔗

constexpr exception_ptr current_exception() noexcept;

9

#

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

10

#

Preconditions: p is not a null pointer.

11

#

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.

• (11.1)

If allocating memory to form u fails, throws an instance of bad_alloc;

• (11.2)

otherwise, if copying the exception to which p refers to form u throws an exception, throws that exception;

• (11.3)

otherwise, throws u.

🔗

template<class E> constexpr exception_ptr make_exception_ptr(E e) noexcept;

12

#

Effects: Creates an exception_ptr object that refers to a copy of e, as if:try {throw e;} catch(...) {return current_exception();}

13

#

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

14

#

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]

15

#

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.