# Exception-safety guarantees

> How stack unwinding interacts with class invariants: the Abrahams guarantees, noexcept move optimization, copy-and-swap, and unwinding traps.

- **Source:** C++ Atlas (https://cppatlas.com/topics/exception-safety-guarantees)
- **Track:** Exceptions and error handling
- **Estimated reading time:** 10 minutes
- **ISO C++ clauses:** [except] (https://eel.is/c++draft/except), [except.throw] (https://eel.is/c++draft/except.throw), [except.spec] (https://eel.is/c++draft/except.spec), [except.handle] (https://eel.is/c++draft/except.handle), [except.terminate] (https://eel.is/c++draft/except.terminate), [class.dtor] (https://eel.is/c++draft/class.dtor)
- **cppreference links:** [Exceptions](https://en.cppreference.com/w/cpp/language/exceptions), [noexcept specifier](https://en.cppreference.com/w/cpp/language/noexcept_spec), [Throwing exceptions](https://en.cppreference.com/w/cpp/language/throw), [std::move_if_noexcept](https://en.cppreference.com/w/cpp/utility/move_if_noexcept), [std::uncaught_exceptions](https://en.cppreference.com/w/cpp/error/uncaught_exception), [std::terminate](https://en.cppreference.com/w/cpp/error/terminate)
- **Prerequisites:** raii-and-resource-management, copy-and-move

Exceptions separate error detection from error handling across arbitrarily deep call stacks. That flexibility comes with a contract: whenever any expression inside a function throws, every object along the unwound path must remain in a valid state so destructors and enclosing error handlers can reason about what survived.

Exception safety is not a single yes-or-no boolean. David Abrahams formalized four distinct levels of guarantees a function can provide when an operation fails, ranging from zero failure modes down to broken invariants.

## The Abrahams exception-safety hierarchy

Every function in a well-designed C++ codebase sits at a deliberate rung on the exception-safety ladder.

| Guarantee | Observable state after throw | Resource leaks | Typical examples |
| --- | --- | --- | --- |
| Nothrow / Nofail | Operation always succeeds | Never | `swap`, `~T()`, `move` constructors |
| Strong | Identical to state before call | Never | `std::vector::push_back`, copy-and-swap |
| Basic | Valid invariants, unspecified values | Never | Multi-element `std::vector::insert`, `std::sort` |
| None | Broken invariants or leaked handles | Possible | Raw manual `new`/`delete` without RAII |

The **nothrow** (or **nofail**) guarantee promises that an operation never emits an exception—either because nothing inside it can fail, or because failures are absorbed internally. Without a nothrow foundation for `swap`, destructors, and pointer transfers, higher guarantees collapse.

The **strong guarantee** delivers transactional commit-or-rollback semantics: if an exception escapes, the program state rolls back completely as if the call never happened. Standard containers such as `std::vector::push_back` provide this guarantee whenever element relocation does not prevent it.

The **basic guarantee** is the mandatory baseline for almost all production C++ code. An exception may leave mutated objects holding partial updates—a vector might contain half of a batch, or a string might keep its new capacity—yet zero resources leak, class invariants hold, and every surviving object can still be inspected, assigned, or destroyed safely.

> **Mental model.** Strong exception safety is simply a two-phase transaction: perform every allocation or copy that might throw on isolated side state, then commit the result to `this` using exclusively `noexcept` operations.

## Stack unwinding and the exception object

When a `throw expr;` expression executes, the runtime first initializes an **exception object** in unspecified memory (never on the stack frame about to be torn down) by copy- or move-initializing from `expr`, potentially applying copy elision. Control then walks outward through enclosing scopes until a matching `catch` handler is found.

During this **stack unwinding**, automatic objects whose initialization has already completed are destroyed in exact reverse order of construction completion. Partially constructed aggregates and classes receive selective cleanup: if a constructor body or member initializer throws midway through constructing member `b` after member `a` succeeded, the destructor of `a` runs automatically, while the class's own destructor `~Class()` does **not** run because the object never finished beginning its lifetime.

> **Standardese.** Under `[except.throw]` and `[except.terminate]`, if no matching handler exists anywhere on the call stack, or if unwinding encounters a function marked `noexcept(true)`, the implementation calls `std::terminate()`—and it is implementation-defined whether stack unwinding even runs destructors before termination.

## Strong guarantee via copy-and-swap and commit phases

Writing `operator=` manually with raw resources easily violates even the basic guarantee:

```cpp
// Broken: if `new` throws, `data_` is left dangling!
RawBuffer& operator=(const RawBuffer& rhs) {
    delete[] data_;
    data_ = new std::byte[rhs.size_]; // throws std::bad_alloc -> UB on ~RawBuffer
    size_ = rhs.size_;
    return *this;
}
```

The idiomatic cure is **copy-and-swap**, which moves every fallible step (memory allocation and element copying) into the by-value parameter construction before executing a non-throwing swap:

```cpp
#include <algorithm>
#include <cstddef>
#include <memory>
#include <utility>

class PacketBuffer {
    std::unique_ptr<std::byte[]> data_;
    std::size_t size_ = 0;

public:
    PacketBuffer() = default;
    explicit PacketBuffer(std::size_t n)
        : data_(std::make_unique<std::byte[]>(n)), size_(n) {}

    PacketBuffer(const PacketBuffer& other)
        : data_(other.size_ ? std::make_unique<std::byte[]>(other.size_) : nullptr),
          size_(other.size_) {
        if (size_) std::copy_n(other.data_.get(), size_, data_.get());
    }

    PacketBuffer(PacketBuffer&&) noexcept = default;

    void swap(PacketBuffer& other) noexcept {
        using std::swap;
        swap(data_, other.data_);
        swap(size_, other.size_);
    }

    // Parameter construction may throw before entry; body is nothrow.
    PacketBuffer& operator=(PacketBuffer rhs) noexcept {
        swap(rhs);
        return *this;
    }
};
```

Here `rhs` acts as a temporary staging buffer. If copying throws `std::bad_alloc`, `*this` stays untouched—delivering both the strong guarantee and safe self-assignment (`buf = buf`) without extra branches.

When full copy-and-swap would duplicate megabytes across multiple containers, split work into **prepare** and **commit** phases: build new nodes or buffers in local state first, then commit via `noexcept` swaps or pointer transfers.

## Why noexcept controls vector reallocation

Marking a move constructor `noexcept` directly governs standard container performance. During `std::vector::push_back` reallocation, preserving the strong guarantee requires keeping old elements intact until all elements land in the new buffer. If `T`'s move constructor might throw, moving element #3 irreversibly alters the source buffer before element #5 throws.

Therefore `std::vector` relocates elements via `std::move_if_noexcept`, inspecting `std::is_nothrow_move_constructible_v<T>`:

```cpp
#include <string>
#include <type_traits>
#include <utility>

struct FragileMove {
    std::string label;
    FragileMove(FragileMove&& other) : label(std::move(other.label)) {} // NOT noexcept
    FragileMove(const FragileMove&) = default;
};

struct FastMove {
    std::string label;
    FastMove(FastMove&&) noexcept = default;
    FastMove(const FastMove&) = default;
};

static_assert(!std::is_nothrow_move_constructible_v<FragileMove>);
static_assert(std::is_nothrow_move_constructible_v<FastMove>);
```

> **Pitfall.** Defining a custom move constructor without `noexcept` silently forces `std::vector` to copy every element instead of moving on reallocation whenever a copy constructor exists—turning expected pointer swaps into expensive deep allocations.

For generic wrappers, write **conditional `noexcept`** expressions rather than guessing: `Wrapper(Wrapper&& other) noexcept(std::is_nothrow_move_constructible_v<T>)`. Meanwhile, move-only types (`std::unique_ptr`, or custom non-copyable handles) still get moved during `std::vector` growth because copying is unavailable, though leaving their move constructors non-`noexcept` downgrades `push_back` from the strong guarantee to the basic guarantee.

## Destructors, function-try-blocks, and uncaught_exceptions

Since C++11, every destructor is **implicitly `noexcept(true)`** unless a non-static member or base subobject has a potentially throwing destructor or the destructor explicitly declares `noexcept(false)` (`[class.dtor]`). Throwing an exception out of an implicitly `noexcept` destructor—whether during normal scope exit or during stack unwinding—immediately triggers `std::terminate()`.

Even if a destructor explicitly specifies `noexcept(false)`, letting an exception escape while another exception is already unwinding (`std::uncaught_exceptions() > 0`) still invokes `std::terminate()`. Destructors must therefore swallow, log, or assert on internal failures rather than emitting exceptions.

Two specialized language features interact closely with unwinding:

1. **Constructor function-try-blocks** wrap member initializers so you can log or translate exceptions thrown by bases or members. However, per `[except.handle]`, a `catch` block on a constructor or destructor cannot suppress the exception silently: reaching the closing brace without throwing a different exception or calling `return` (invalid in constructors) **implicitly rethrows** the active exception.

2. **`std::uncaught_exceptions()`** (plural, C++17) returns the count of active exceptions currently in flight on the calling thread—replacing the deprecated C++98 `bool std::uncaught_exception()`, which could not tell whether an exception was thrown *inside* a scope guard's lifetime when the guard itself was created during an outer stack unwind:

```cpp
#include <exception>
#include <utility>

template <class Fn>
class RollbackGuard {
    Fn rollback_;
    int entry_count_ = std::uncaught_exceptions();

public:
    explicit RollbackGuard(Fn fn) : rollback_(std::move(fn)) {}
    RollbackGuard(const RollbackGuard&) = delete;

    ~RollbackGuard() {
        if (std::uncaught_exceptions() > entry_count_) {
            rollback_();
        }
    }
};
```

Comparing the exit count against the entry snapshot lets transaction guards distinguish new failures from pre-existing outer unwinds cleanly.

> **Pitfall.** Placing a `try { ... } catch (...) {}` function-try-block on a constructor does not prevent the caller from receiving an exception; if execution reaches the end of the handler, C++ automatically rethrows.

## What to remember

- The **basic guarantee** (no leaks, valid invariants) is the non-negotiable minimum for all C++ types; achieve it effortlessly by owning resources through RAII handles.
- Achieve the **strong guarantee** by performing every potentially throwing allocation or copy on temporary state first, then committing via `noexcept` swaps or pointer transfers.
- Always mark user-declared move constructors and move assignment operators `noexcept` when they cannot throw, or `std::move_if_noexcept` will force containers like `std::vector` back into copying.
- Destructors are implicitly `noexcept(true)` since C++11; never let exceptions escape a destructor, and use `std::uncaught_exceptions()` (plural) to detect new unwinds inside scope guards.
- A constructor function-try-block can observe or translate a member-initializer exception, never swallow it.

## Concept Map Outline

- **Exception-Safety Guarantees:** Contracts governing object invariants, resource cleanup, and container behavior when C++ code throws.
  - **Abrahams Guarantee Levels:** Four graduated promises defining what state survives an exception.
    - **Nothrow and Nofail:** Operations guaranteed never to emit exceptions, forming the bedrock for commit phases.
    - **Strong Commit-Rollback:** Failed calls leave program state identical to before the call began.
    - **Basic No-Leak Invariants:** Mandatory baseline guaranteeing zero leaked resources and destructible, valid objects.
  - **Stack Unwinding Mechanics:** How runtime cleanup executes between throw and catch.
    - **Exception Object Storage:** Throw initializes an implementation-managed exception object outside unwinding frames.
    - **Partial Subobject Cleanup:** Completed bases and members destroy in reverse order while the outer destructor is skipped.
    - **std::terminate Triggers:** Uncaught exceptions or throws escaping noexcept functions abort without guaranteed unwinding.
  - **Strong Guarantee Patterns:** Idioms that isolate failure-prone work from state mutation.
    - **Copy-and-Swap Idiom:** By-value parameter construction isolates allocations before a nothrow swap mutates this.
    - **Prepare-Then-Commit Split:** Stage new allocations locally first, then publish with noexcept swaps and pointer moves.
  - **noexcept and Move Semantics:** Compile-time checks linking exception specs to container efficiency.
    - **std::move_if_noexcept:** Containers copy instead of moving unless the move constructor is noexcept or non-copyable.
    - **Conditional noexcept:** Propagate member noexcept traits using noexcept(expr) on generic wrappers.
    - **Implicitly noexcept Destructors:** Every destructor defaults to noexcept(true) unless a subobject or specifier opts out.
  - **Unwinding Edge Cases:** Language rules around constructor handlers and nested exceptions.
    - **Constructor Function-Try Blocks:** Handlers around member initializers can translate errors but implicitly rethrow on exit.
    - **std::uncaught_exceptions Depth:** Counting active exceptions lets scope guards detect new unwinds inside outer catches.

## Standardese Quiz Questions

### Question 1 [warmup] ([except], [res.on.exception.handling])

What does the basic exception-safety guarantee promise if a member function throws an exception?

A. All modified objects automatically roll back to their exact pre-call values
B. No resources are leaked and all class invariants remain intact, though values may have changed
C. The function is implicitly marked noexcept and calls std::terminate on error
D. Only stack-allocated primitives are rolled back while heap memory may leak

**Answer (B):** No resources are leaked and all class invariants remain intact, though values may have changed

**Why:** The basic guarantee requires zero resource leaks and preserved invariants so surviving objects remain valid and destructible, without promising value rollback (which is the strong guarantee).

### Question 2 [warmup] ([vector.modifiers], [utility.move.if.noexcept])

Why does std::vector::push_back copy elements instead of moving them during buffer reallocation when a copyable type's move constructor lacks noexcept?

```cpp
struct S {
    S(const S&);
    S(S&&); // not noexcept
};
```

A. The standard forbids calling non-noexcept move constructors anywhere in <vector>
B. Copy constructors are always faster than move constructors for small buffers
C. Moving irreversibly alters the source buffer, so throwing mid-reallocation would break push_back's strong guarantee
D. Non-noexcept move constructors make std::is_move_constructible_v<S> false

**Answer (C):** Moving irreversibly alters the source buffer, so throwing mid-reallocation would break push_back's strong guarantee

**Why:** std::vector uses std::move_if_noexcept to preserve its strong exception-safety guarantee on reallocation: if moving element i can throw, the old elements are already mutated, preventing rollback. When copy construction is available, vector falls back to copying.

### Question 3 [tricky] ([except.ctor], [basic.life])

In the snippet below, what happens if Foo's second member initializer (b(arg)) throws an exception?

```cpp
struct Foo {
    A a;
    B b;
    Foo(int arg) : a(), b(arg) {}
    ~Foo() { cleanup(); }
};
```

A. ~A() runs to destroy the completed subobject, and ~Foo() does not run
B. ~Foo() runs first, followed by ~A()
C. Neither ~A() nor ~Foo() runs because Foo never finished constructing
D. Both ~B() and ~A() run in reverse declaration order

**Answer (A):** ~A() runs to destroy the completed subobject, and ~Foo() does not run

**Why:** An object's lifetime begins only when its constructor completes. When b(arg) throws, b never began lifetime and Foo never finished construction, so ~Foo() and ~B() are skipped—only already-constructed subobjects (a) are destroyed in reverse order.

### Question 4 [tricky] ([uncaught.exceptions])

Why did C++17 introduce int std::uncaught_exceptions() to replace bool std::uncaught_exception()?

A. uncaught_exception() returned false inside noexcept functions
B. uncaught_exception() had a data race across threads
C. uncaught_exceptions() automatically suppresses secondary exceptions thrown in destructors
D. A boolean cannot distinguish a new inner exception from an outer unwind already active when a scope guard was constructed

**Answer (D):** A boolean cannot distinguish a new inner exception from an outer unwind already active when a scope guard was constructed

**Why:** If a RAII transaction guard is constructed inside a catch block or destructor during an outer unwind, uncaught_exception() is already true throughout its scope. Comparing exit count against entry count via std::uncaught_exceptions() accurately detects new unwinding.

### Question 5 [standardese] ([class.dtor], [except.spec])

In modern C++ (C++11 and later), what is the implicit exception specification of TrackedHolder::~TrackedHolder() below?

```cpp
struct Tracked {
    ~Tracked() noexcept(false) {}
};
struct TrackedHolder {
    Tracked t;
    ~TrackedHolder() = default;
};
```

A. noexcept(true), because all destructors are unconditionally noexcept
B. Potentially throwing (noexcept(false)), inherited from member subobject Tracked::~Tracked()
C. Ill-formed because a defaulted destructor cannot contain a throwing member
D. noexcept(true) unless TrackedHolder also holds a virtual base

**Answer (B):** Potentially throwing (noexcept(false)), inherited from member subobject Tracked::~Tracked()

**Why:** Per [class.dtor] and [except.spec], a destructor with no explicit noexcept specifier has the same exception specification as an implicitly declared one—which is noexcept(true) ONLY if all direct base and non-static member destructors are non-throwing. Tracked::~Tracked() is noexcept(false), making ~TrackedHolder() potentially throwing too.

### Question 6 [standardese] ([except.handle])

What happens when execution reaches the closing brace of the catch block in Wrapper's constructor function-try-block?

```cpp
struct Wrapper {
    Widget w;
    Wrapper(int x) try : w(x) {
    } catch (...) {
        log_error();
    }
};
```

A. Wrapper finishes constructing with w left uninitialized
B. The caught exception is swallowed and Wrapper throws std::bad_exception
C. The currently handled exception is implicitly rethrown
D. std::terminate() is called unconditionally

**Answer (C):** The currently handled exception is implicitly rethrown

**Why:** Under [except.handle], if control reaches the end of a handler of a function-try-block on a constructor or destructor without exiting via throw, the current exception is automatically rethrown—a constructor cannot recover and produce a half-constructed object.
