std::uncaught_exception, std::uncaught_exceptions

 

C++

Compiler support

Freestanding and hosted

Language

Standard library

Standard library headers

Named requirements

Feature test macros (C++20)

Language support library

Concepts library (C++20)

Metaprogramming library (C++11)

Diagnostics library

General utilities library

Strings library

Containers library

Iterators library

Ranges library (C++20)

Algorithms library

Numerics library

Localizations library

Input/output library

Filesystem library (C++17)

Regular expressions library (C++11)

Concurrency support library (C++11)

Execution support library (C++26)

Technical specifications

Symbols index

External libraries

 

Diagnostics library

Exception handling exception uncaught_exceptionuncaught_exceptions (until C++20*)  (C++17) exception_ptr (C++11) make_exception_ptr (C++11) current_exception (C++11) rethrow_exception (C++11) nested_exception (C++11) throw_with_nested (C++11) rethrow_if_nested (C++11) Exception handling failures terminate terminate_handler get_terminate (C++11) set_terminate bad_exception unexpected (until C++17*) unexpected_handler (until C++17*) get_unexpected (until C++17*) set_unexpected (until C++17*) Error numbers Error codes errno Assertions assert

Exception categories logic_error invalid_argument domain_error length_error out_of_range runtime_error range_error overflow_error underflow_error tx_exception (TM TS) System error error_category (C++11) generic_category (C++11) system_category (C++11) error_condition (C++11) errc (C++11) error_code (C++11) system_error (C++11) Stacktrace stacktrace_entry (C++23) basic_stacktrace (C++23) Debugging support is_debugger_present (C++26) breakpoint_if_debugging (C++26) breakpoint (C++26)

 

Defined in header <exception>
	(1)
bool uncaught_exception() throw();			(until C++11)
bool uncaught_exception() noexcept;			(since C++11) (deprecated in C++17) (removed in C++20)
int uncaught_exceptions() noexcept;		(2)	(since C++17)

1) Detects if the current thread has a live exception object, that is, an exception has been thrown or rethrown and not yet entered a matching catch clause, std::terminate or std::unexpected. In other words, std::uncaught_exception detects if stack unwinding is currently in progress.

2) Detects how many exceptions in the current thread have been thrown or rethrown and not yet entered their matching catch clauses.

Sometimes it's safe to throw an exception even while std::uncaught_exception() == true. For example, if stack unwinding causes an object to be destructed, the destructor for that object could run code that throws an exception as long as the exception is caught by some catch block before escaping the destructor.

Parameters

(none)

Return value

1) true if stack unwinding is currently in progress in this thread, false otherwise.

2) The number of uncaught exception objects in the current thread.

Notes

An example where int-returning uncaught_exceptions is used is the boost.log library: the expression BOOST_LOG(logger) << foo(); first creates a guard object and records the number of uncaught exceptions in its constructor. The output is performed by the guard object's destructor unless foo() throws (in which case the number of uncaught exceptions in the destructor is greater than what the constructor observed).

std::experimental::scope_fail and std::experimental::scope_success in LFTS v3 rely on the functionality of uncaught_exceptions, because their destructors need to do different things that depend on whether is called during stack unwinding.

Feature-test macro	Value	Std	Feature
__cpp_lib_uncaught_exceptions	201411L	(C++17)	std::uncaught_exceptions

Example

Run this code

#include <exception>
#include <iostream>
#include <stdexcept>
 
struct Foo
{
    char id{'?'};
    int count = std::uncaught_exceptions();
 
    ~Foo()
    {
        count == std::uncaught_exceptions()
            ? std::cout << id << ".~Foo() called normally\n"
            : std::cout << id << ".~Foo() called during stack unwinding\n";
    }
};
 
int main()
{
    Foo f{'f'};
 
    try
    {
        Foo g{'g'};
        std::cout << "Exception thrown\n";
        throw std::runtime_error("test exception");
    }
    catch (const std::exception& e)
    {
        std::cout << "Exception caught: " << e.what() << '\n';
    }
}

Possible output:

Exception thrown
g.~Foo() called during stack unwinding
Exception caught: test exception
f.~Foo() called normally

Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

DR	Applied to	Behavior as published	Correct behavior
LWG 70	C++98	the exception specification of uncaught_exception() was missing	specified as throw()

See also

terminate	function called when exception handling fails (function)
exception_ptr (C++11)	shared pointer type for handling exception objects (typedef)
current_exception (C++11)	captures the current exception in a std::exception_ptr (function)

External links

1.	GOTW issue 47: Uncaught Exceptions
2.	Rationale for std::uncaught_exceptions (N4125)