Free, Unlimited Access

Comprehensive course covering advanced concepts, and how to use them on large-scale projects.

Professional C++





<Excerpt>


Whilst handling an exception within a `catch` block, there may be scenarios where yet another exception can occur, thus leaving us with two exceptions being active at the same time.


To handle this, we have the concept of a _**nested exception**_.  This allows us to throw a new exception, and for that exception to include a reference to the original.  So, the original exception is said to be _**nested**_ within the new exception.


</Excerpt>


## Creating Nested Exceptions


To do this, we use the `std::throw_with_nested()` function, passing in our new exception:


```c++
// Auth.h
#pragma once
#include <string>

//<c>
//<l>class AuthenticationError{/*...*/}
class AuthenticationError
  : public std::exception {
 public:
  AuthenticationError(
    std::string Email, std::string Password)
      : Email(Email), Password(Password) {}

  const char* what() const noexcept override {
    return "A user failed to log in";
  };

  std::string Email;
  std::string Password;
};
//</c>

class SecurityError : public std::exception {};

void Auth(
  std::string Email, std::string Password) {
  throw AuthenticationError{Email, Password};
}

void Login(
  std::string Email, std::string Password) {
  try {
    Auth(Email, Password);
  } catch (AuthenticationError& e) {
    std::throw_with_nested(SecurityError{});  //<h>
  }
}
```


Above, our `Login()` function will emit a `SecurityError`, with an `AuthenticationError` nested within it.  We can catch the `SecurityError` in the normal way:


```c++
#include <iostream>
#include "Auth.h"

int main() {
  try {
    Login("test@example.com", "secret");
  } catch (SecurityError& e) {
    std::cout << "Caught a SecurityError";
  }
  std::cout << "\nProgram recovered";
}
```


When we handle the exception in this way, we also handle any nested exceptions that it might have contained.  As a result, our program fully recovers:


```c++
//<o>
Caught a SecurityError
Program recovered
```


Typically, however, this is not what we want.  If we’re using nested exceptions in our project, we need to consider the possibility that the exceptions we receive might contain nested exceptions that also need to be handled.  We cover techniques on how to do this in the next few sections.


## Accessing Nested Exceptions


The `throw_with_nested()` function implements nested exceptions using _**multiple inheritance**_, meaning a class can inherit from multiple base classes.  This is a technique we’ll cover in detail later in the course.


For now, we can think of the object created by `throw_with_nested()` as having _**two**_ types.  One of the types is `std::nested_exception`, and the other is the type of object we provided as an argument.  In the previous example, that was our user-defined type `SecurityError`:


```c++
std::throw_with_nested(SecurityError{});
```


To check if our type is a `std::nested_exception`, we can `dynamic_cast` it in the usual way:


```c++
#include <iostream>
#include "Auth.h"

int main() {
  try {
    Login("test@example.com", "secret");
  } catch (SecurityError& e) {
    std::cout << "Caught a SecurityError";

    auto NestedException{
      dynamic_cast<std::nested_exception*>(&e)};
    if (NestedException) {
      std::cout <<
        "\nThere's a nested exception in here";
    }
  }
  std::cout << "\nProgram recovered";
}
```


```c++
//<o>
Caught a SecurityError
There's a nested exception in here
Program recovered
```


However, the easiest way to detect and deal with nested exceptions tends to be to _**rethrow**_ them.


<Ad />


## Rethrowing Nested Exceptions


Once we’ve dealt with the outer exception, we can decide to rethrow the nested exception, if there is one.


The easiest way to do this is through the `std::rethrow_if_nested()` function:


```c++
#include <iostream>
#include "Auth.h"

int main() {
  try {
    Login("test@example.com", "secret");
  } catch (SecurityError& e) {
    std::cout << "Caught a SecurityError";

    try {
      std::rethrow_if_nested(e);//<h>
    } catch (...) {
      std::cout << "\nThere's a nested "
        "exception in here";
    }
  }
  std::cout << "\nProgram recovered";
}
```


```c++
//<o>
Caught a SecurityError
There's a nested exception in here
Program recovered
```


As we might expect, we can handle a nested exception like any other.  Our `catch` block can specify the exception type it is capable of handling:


```c++
#include <iostream>
#include "Auth.h"

int main() {
  try {
    Login("test@example.com", "secret");
  } catch (SecurityError& e) {
    std::cout << "Caught a SecurityError";

    try {
      std::rethrow_if_nested(e);
    } catch (AuthenticationError& e) {
      std::cout
        << "\nNested AuthenticationError: "
        << e.Email;
    }
  }
  std::cout << "\nProgram recovered";
}
```


```c++
//<o>
Caught a SecurityError
Nested AuthenticationError: test@example.com
Program recovered
```


Also, we don’t need to handle nested exceptions locally.  We can just throw them and let a function elsewhere on the call stack deal with it:


```c++
void SomeFunction() {
  try {
    Login("test@example.com", "secret");
  } catch (SecurityError& e) {
    std::cout << "Caught a SecurityError";
    std::rethrow_if_nested(e);//<h>
  }
}
```


## Handling Nested Exceptions Recursively


Exceptions can be nested arbitrarily deeply.  For example, in a complex project that uses nested exceptions, we can have an exception, nested within an exception, nested within another exception.


The contrived `GenerateExceptions()` function simulates this scenario:


```c++
#include <iostream>

void GenerateExceptions() {
  try {
    throw std::runtime_error{"Error One"};
  } catch (...) {
    try {
      std::throw_with_nested(
        std::runtime_error{"Error Two"});
    } catch (...) {
      std::throw_with_nested(
        std::runtime_error{"Error Three"});
    }
  }
}
```


When we catch an exception, we’ll often want to unwind _**all**_ of the exceptions contained within it.  In the following example, the `HandleExceptions()` function demonstrates how we can do this:


```c++
#include <iostream>

//<c>
//<l>void GenerateExceptions() {/*...*/}
void GenerateExceptions() {
  try {
    throw std::runtime_error{"Error One"};
  } catch (...) {
    try {
      std::throw_with_nested(
        std::runtime_error{"Error Two"});
    } catch (...) {
      std::throw_with_nested(
        std::runtime_error{"Error Three"});
    }
  }
}
//</c>

void HandleExceptions(const std::exception& e) {
  std::cout << "\nHandling " << e.what();
  try {
    std::rethrow_if_nested(e);
  } catch (const std::exception& Nested) {
    HandleExceptions(Nested); // Recursion//<h>
  }
}

int main() {
  try {
    GenerateExceptions();
  } catch (std::exception& e) {
    HandleExceptions(e);
  }
}
```


```c++
//<o>
Handling Error Three
Handling Error Two
Handling Error One
```


This is an example of a _**recursive function**_.  A recursive function conditionally calls _**itself**_.


In this case, `HandleException()` calls itself if `std::rethrow_if_nested(e);` throws an exception.  In other words, it calls itself if the exception it received as a parameter contains a nested exception.


This works because each call to `HandleExceptions()` catches and handles the current nested exception, then calls itself again with the next nested exception. This process repeats, unwinding the nested exceptions from the inside out, until `std::rethrow_if_nested(e)` doesn't throw anymore, indicating there are no more nested exceptions.


Recursion is a relatively unintuitive concept, so don’t worry if this examples doesn’t make sense.  We cover recursion starting with simpler examples in a dedicated lesson later in the course.


## Summary


This lesson provided an exploration of nested exceptions, demonstrating their implementation, handling, and practical applications. The key topics we learned included:

- Understanding of nested exceptions and their usage with `std::throw_with_nested()` for handling multiple layers of exceptions.
- Familiarity with accessing and identifying nested exceptions using `dynamic_cast` and `std::nested_exception`.
- Knowledge of rethrowing nested exceptions using `std::rethrow_if_nested()` and handling them appropriately.
- Insight into recursively handling deeply nested exceptions, showcasing how to systematically unravel and address each layer of errors.

<FAQ>


```javascript
//<m>
{
  slug: 'throw-with-nested-non-exception',
  title: 'Throwing Non-Exceptions with std::throw_with_nested()',
  question: 'What happens if I pass a non-exception type to `std::throw_with_nested()`?',
}
```


If you pass a non-exception type to `std::throw_with_nested()`, the behavior is undefined. The C++ standard requires that the argument to `std::throw_with_nested()` be derived from `std::exception`.


For example, this code has undefined behavior:


```c++
try {
  std::throw_with_nested(42);//<e>
} catch(...) {
// undefined behavior
}
```


To properly use `std::throw_with_nested()`, ensure you only pass it exceptions:


```c++
try {
  std::throw_with_nested(
    std::runtime_error{"Error"});  //<h>
} catch (...) {
  // OK, runtime_error derives from std::exception
}
```


</FAQ>


<FAQ>


```javascript
//<m>
{
  slug: 'multiple-catch-blocks-nested-exceptions',
  title: 'Handling Nested Exceptions with Multiple Catch Blocks',
  question: 'Can I handle nested exceptions using multiple catch blocks? If so, in what order are they caught?',
}
```


Yes, you can use multiple `catch` blocks to handle nested exceptions. The `catch` blocks will be tried in order, and the first one that matches the exception type will be executed.


For example:


```c++
try {
  try {
    throw std::runtime_error{"Inner Exception"};
  } catch (...) {
    std::throw_with_nested(
      std::logic_error{"Outer Exception"});
  }
} catch (std::logic_error& e) {
  std::cout << "Caught logic_error: "
    << e.what() << '\n';
  // Rethrow the std::runtime_error if desired
  // std::rethrow_if_nested(e);
}
```


```text
//<o>
Caught logic_error: Outer Exception
```


In this example, the `std::logic_error` is caught first because it's the type we directly threw. When we call `std::rethrow_if_nested(e)`, it then throws the nested `std::runtime_error`, which is caught by the next matching `catch` block.


</FAQ>


<FAQ>


```javascript
//<m>
{
  slug: 'nested-exceptions-performance',
  title: 'Performance Impact of Nested Exceptions',
  question: 'Is there a performance penalty when using nested exceptions compared to regular exceptions?',
}
```


Using nested exceptions does introduce some overhead compared to regular exceptions:

1. `std::throw_with_nested()` dynamically allocates memory to create the nested exception object. This allocation has some time and space overhead.
2. Unwinding nested exceptions requires additional processing. With regular exceptions, the runtime just needs to find the nearest matching `catch` block. With nested exceptions, it needs to recursively unwind each level of nesting.

However, in most cases this overhead is negligible and is outweighed by the benefits of more expressive error handling. Exceptions should be used for exceptional circumstances anyway, not in performance-critical paths.


If you do find that exception handling is a bottleneck in your code, you can consider techniques like:

- Use non-throwing functions where possible in performance-critical code.
- Catch exceptions by reference to avoid copying.
- Use `noexcept` to mark functions that don't throw, allowing the compiler to optimize.

But in general, the performance impact of nested exceptions specifically is not something to worry about prematurely. Use them when they make your error handling clearer and more robust.


</FAQ>


<FAQ>


```javascript
//<m>
{
  slug: 'nested-exceptions-across-threads',
  title: 'Propagating Nested Exceptions Across Threads',
  question: 'Can I throw a nested exception from one thread and catch it in another thread?',
}
```


Yes, you can propagate nested exceptions across threads, with some caveats.


In C++11 and later, if a function called by `std::thread` exits with an uncaught exception, the runtime captures that exception and stores it. When you call `join()` or `get()` on the `std::thread` or `std::future` object, it will rethrow that stored exception.


This works with nested exceptions too. If the thread function exits with an uncaught nested exception, it will be captured and rethrown when `join()` or `get()` is called.


For example:


```c++
#include <exception>
#include <iostream>
#include <thread>

void thread_func() {
  try {
    throw std::runtime_error{"Inner Exception"};
  } catch (...) {
    std::throw_with_nested(
      std::logic_error{"Outer Exception"});
  }
}

void join_thread() {
  try {
    std::thread t{thread_func};
    t.join();
  } catch (const std::exception& e) {
    std::cout << "Caught exception: " << e.what() << '\n';
    // Rethrow the std::runtime_error if desired
    // std::rethrow_if_nested(e);
  }
}
```


However, there are some limitations:

1. The exception types must be copyable, because the exception is copied into the `std::thread` or `std::future` object.
2. If the thread function exits via other means (e.g., by calling `std::terminate`), the behavior is undefined.
3. If the `std::thread` or `std::future` object is destroyed without calling `join()` or `get()`, the stored exception is lost and `std::terminate` is called.

So while you can propagate nested exceptions across threads, it's important to handle and rethrow them properly to avoid unexpected behavior.


</FAQ>


<FAQ>


```javascript
//<m>
{
  slug: 'nested-exceptions-destructors',
  title: 'Throwing Nested Exceptions from Destructors',
  question: 'Is it safe to throw nested exceptions from a destructor?',
}
```


No, it's not safe to throw any exceptions, including nested exceptions, from a destructor.


In C++, destructors are called in many situations, including during stack unwinding when an exception is thrown. If a destructor itself throws an exception during this process, it leads to undefined behavior, typically resulting in immediate termination of the program.


Here's an example of what not to do:


```c++
#include <stdexcept>

class Dangerous {
public:
  ~Dangerous() {
    try {
      throw std::runtime_error{
        "Inner Exception"};
    } catch(...) {
      std::throw_with_nested(std::logic_error{//<e>
        "Outer Exception"});//<e>
    }
  }
};

int main() {
  try {
    Dangerous d;
    throw std::exception{};
  } catch(const std::exception&) {
  }
}
```


In this code, when the `std::exception` is thrown in `main()`, the `Dangerous` object `d` will be destroyed as part of stack unwinding. But its destructor throws another exception, leading to undefined behavior.


To avoid this, the C++ standard specifies that destructors should not throw exceptions. If a destructor needs to handle an exception, it should catch and handle it internally, not let it propagate.


For example:


```c++
#include <stdexcept>
#include <iostream>

class SaferButNotIdeal {
 public:
  ~SaferButNotIdeal() noexcept {
    try {
      // Some operation that might throw
      throw std::exception{};
    } catch (...) {
      // Handle the exception, but don't rethrow
      std::cout << "Caught exception in "  //<h>
                   "destructor\n";         //<h>
    }
  }
};

int main() {
  SaferButNotIdeal s;
}
```


```c++
//<o>
Caught exception in destructor
```


Even better is to design your classes so that their destructors don't throw in the first place, by ensuring all operations in the destructor are non-throwing.


</FAQ>


<FAQ>


```javascript
//<m>
{
  slug: 'nested-exceptions-across-dlls',
  title: 'Propagating Nested Exceptions Across DLL Boundaries',
  question: 'Can I throw a nested exception from a function in a DLL and catch it in the calling code?',
}
```


Propagating exceptions, including nested exceptions, across DLL (dynamically linked library) boundaries is possible but requires careful design.


The main challenge is that the DLL and the calling code might use different memory allocators. If an exception is allocated in the DLL using the DLL's allocator, but then caught and deallocated in the calling code using the calling code's allocator, it can lead to runtime errors or memory corruption.


To safely propagate exceptions across DLL boundaries:

1. The DLL and the calling code should use the same C++ runtime library, to ensure they use the same memory allocator.
2. The exception types should be defined in a header file that is shared between the DLL and the calling code, to ensure they have the same definition.
3. The exception types should have a non-throwing destructor, to avoid the issues with throwing destructors mentioned in the previous answer.
4. The DLL function should catch any internal exceptions and translate them into error codes or exceptions that are part of the DLL's public interface.

Here's an example:


```c++
// DLL.cpp
#include <stdexcept>
#include "SharedTypes.h"

// SharedTypes.h
struct DLLException : std::exception {
  const char* what() const noexcept override {
    return "Exception from DLL"; }
};

extern "C" __declspec(dllexport)
void DLLFunction() {
  try {
    // Some operation that might throw
    throw std::runtime_error{"Internal error"};
  } catch (...) {
    std::throw_with_nested(DLLException{});  //<h>
  }
}
```


```c++
// Main.cpp
#include <iostream>
#include "SharedTypes.h"

int main() {
  try {
    DLLFunction();
  } catch (const DLLException& e) {
    std::cout << "Caught DLLException: "
      << e.what() << '\n';
    std::rethrow_if_nested(e);
  } catch (const std::exception& e) {
    std::cout << "Caught nested exception: "
      << e.what() << '\n';
  }
}
```


In this design, the `DLLFunction` catches any internal exceptions and wraps them in a `DLLException`, which is defined in a shared header file. The `main` function can then catch `DLLException` and access any nested exceptions.


However, even with this design, there are still potential pitfalls. For maximum portability and safety, it's often better for DLL functions to return error codes instead of throwing exceptions.


</FAQ>



Learn about nested exceptions in C++: from basic concepts to advanced handling techniques

Throwing Non-Exceptions with std::throw_with_nested()

Handling Nested Exceptions with Multiple Catch Blocks

Performance Impact of Nested Exceptions

Propagating Nested Exceptions Across Threads

Throwing Nested Exceptions from Destructors

Propagating Nested Exceptions Across DLL Boundaries

`std::nested_exception` - C++ Reference

`std::rethrow_if_nested()` - C++ Reference

FAQ: Exceptions and Error Handling in C++

UPDATED FOR C++23 | Dive deep into nested exceptions in C++, understanding how to implement, identify, and handle them. | Clear explanations and simple code examples

Propagating Nested Exceptions Across Threads

Can I throw a nested exception from one thread and catch it in another thread?

Nested Exceptions

What happens if I pass a non-exception type to std::throw_with_nested()?

Can I handle nested exceptions using multiple catch blocks? If so, in what order are they caught?

Is there a performance penalty when using nested exceptions compared to regular exceptions?

Is it safe to throw nested exceptions from a destructor?

Can I throw a nested exception from a function in a DLL and catch it in the calling code?

Nested Exceptions

Professional C++

This course includes:

Professional C++

What happens if I pass a non-exception type to `std::throw_with_nested()`?