Skip to content
Tutorials Center
My learning

Topics

C++ Reference ยท Memory and Utilities

C++ std::unreachable and [[assume]]

Reference for std::unreachable (C++23) and the [[assume]] attribute: tell the compiler what cannot happen, what it enables and why wrong hints are undefined.

C++23 added two ways to tell the optimizer about facts it cannot prove. std::unreachable() (header <utility>) marks a point that control flow can never reach. The attribute [[assume(expression)]] states that an expression is true at that point. The compiler is allowed to build on both claims, for instance by deleting checks and branches it now considers dead.

These are promises, not checks. If a promise is false at run time, the behavior of the program is undefined: no exception, no message, possibly a silent wrong answer or a jump into random code. Use them sparingly, after profiling, and keep a normal assertion in debug builds.

C++
switch (kind) {
    case Kind::A: return 1;
    case Kind::B: return 2;
}
std::unreachable();   // kind is always A or B

Try it

C++ unreachable after a full switch

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.

C++ [[assume]] on loop counts

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.

Syntax

C++
[[noreturn]] void std::unreachable();      // <utility>, C++23

[[assume(expression)]];                    // attribute statement, C++23
Name Description
std::unreachable() Reaching this call is undefined behavior. It never returns.
expression Contextually converted to bool. It is not evaluated, so side effects do not happen.

Returns: unreachable does not return. [[assume]] produces nothing.

Undefined behavior: if control reaches std::unreachable(), or if the assumed expression would evaluate to false (or would throw or have undefined behavior), the program has undefined behavior.

Usage notes

  • Typical place: after a switch that covers every enumerator. The compiler can then remove the range check on the switch index.
  • Beware enums from outside: a value read from a file or the network may not be one of the enumerators, in which case unreachable is a bug.
  • Never put unreachable() on a path that can run, even "just in case". Use throw, std::abort() or assert there.
  • The assumed expression is not run. [[assume(f())]] does not call f(). Keep it cheap and free of side effects, because the compiler may still emit code to compute it, especially at low optimization levels.
  • Test at your optimization level. Results differ between -O0 and -O2; code with a wrong assumption may seem to work in debug builds.
  • Older spellings: GCC and Clang have __builtin_unreachable(), MSVC has __assume(false). std::unreachable replaces them portably.
  • Alternatives: [[likely]] and [[unlikely]] only hint at probability and never change meaning; assert checks at run time.