MRDOCS_UNREACHABLE

Mark a code path that can never run.

Synopsis

Declared in <mrdocs/Support/Error/Assert.hpp>

#define MRDOCS_UNREACHABLE()

Description

Use it as a statement, with a trailing semicolon, after code that handles every possible case, such as a switch over all enumerators. It also stops "control reaches end of non‐void function" warnings, since the compiler knows the path doesn't return:

namespace mrdocs {

enum class Access { Public, Protected, Private };

char const*
toString(Access a)
{
    switch (a)
    {
    case Access::Public:    return "public";
    case Access::Protected: return "protected";
    case Access::Private:   return "private";
    }
    MRDOCS_UNREACHABLE();
}

} // mrdocs

The last line of toString expands to:

// MRDOCS_UNREACHABLE();

// Debug builds: trap at once, so a bug that reaches this
// line stops the program where it happened. No message
// is printed.
static_cast<void>(__builtin_trap(), __builtin_unreachable());
// MSVC: static_cast<void>(__debugbreak(), __assume(false));

// Release builds (NDEBUG): only an optimizer hint.
static_cast<void>(__builtin_unreachable());
// MSVC: static_cast<void>(__assume(false));

In release builds, actually reaching the call is undefined behavior, so don't use it for paths that bad input can reach. Return an error or throw there instead. The macro takes no arguments, but the empty parentheses are required. Unlike MRDOCS_ASSERT, it works in any namespace.

When to use it:

  • In the default: of a switch over a closed kind enum, when every enumerator is already handled, as in the AccessKind and AttributeKind switches in ASTVisitor.cpp.

  • At the end of an exhaustive dispatch, such as the asX() casts generated from the .inc kind lists or the final else of the kind‐id chain in Visitor.hpp.

Use it when the location itself is the bug and there's no condition to test. When you can state the condition that must hold, such as t‐>Kind == T::kind_id before a cast, use MRDOCS_ASSERT instead, so a debug build reports the failed expression. Neither macro is for input a user can control: return an error with MRDOCS_CHECK or MRDOCS_CHECK_OR there.

See Also

MRDOCS_ASSERT

Created with MrDocs