[llvm] [orc-rt] Add ORC_RT_UNREACHABLE / ORC_RT_BUILTIN_UNREACHABLE (PR #209466)

[Lang Hames via llvm-commits]

https://github.com/lhames created https://github.com/llvm/llvm-project/pull/209466

ORC_RT_BUILTIN_UNREACHABLE is an optimizer hint that a location is unreachable, wrapping __builtin_unreachable / __assume(false). Executing it is undefined behavior.

ORC_RT_UNREACHABLE(MSG) marks a point the program must never reach. It aborts with MSG in +Asserts builds; otherwise it lowers to ORC_RT_BUILTIN_UNREACHABLE.

Adds a CompilerTest unit test covering both the returning-function compile path and, in +Asserts builds only, the abort behavior via a death test.

>From 17af5a558c73cced14a444637ba8e7d452b2e578 Mon Sep 17 00:00:00 2001
From: Lang Hames <lhames at gmail.com>
Date: Tue, 14 Jul 2026 22:33:04 +1000
Subject: [PATCH] [orc-rt] Add ORC_RT_UNREACHABLE / ORC_RT_BUILTIN_UNREACHABLE

ORC_RT_BUILTIN_UNREACHABLE is an optimizer hint that a location is
unreachable, wrapping __builtin_unreachable / __assume(false). Executing
it is undefined behavior.

ORC_RT_UNREACHABLE(MSG) marks a point the program must never reach. It
aborts with MSG in +Asserts builds; otherwise it lowers to
ORC_RT_BUILTIN_UNREACHABLE.

Adds a CompilerTest unit test covering both the returning-function
compile path and, in +Asserts builds only, the abort behavior via a
death test.
---
 orc-rt/include/orc-rt/Compiler.h  | 25 ++++++++++++++++++
 orc-rt/test/unit/CMakeLists.txt   |  1 +
 orc-rt/test/unit/CompilerTest.cpp | 43 +++++++++++++++++++++++++++++++
 3 files changed, 69 insertions(+)
 create mode 100644 orc-rt/test/unit/CompilerTest.cpp

diff --git a/orc-rt/include/orc-rt/Compiler.h b/orc-rt/include/orc-rt/Compiler.h
index 8c65ddfab4bbd..77c63289a6aa3 100644
--- a/orc-rt/include/orc-rt/Compiler.h
+++ b/orc-rt/include/orc-rt/Compiler.h
@@ -15,6 +15,8 @@
 #ifndef ORC_RT_COMPILER_H
 #define ORC_RT_COMPILER_H
 
+#include <cassert>
+
 #if defined(_WIN32)
 #define ORC_RT_INTERFACE extern "C"
 #define ORC_RT_HIDDEN
@@ -55,4 +57,27 @@
 #define ORC_RT_WEAK_IMPORT __attribute__((weak))
 #endif
 
+// ORC_RT_BUILTIN_UNREACHABLE: an optimizer hint that the current location is
+// not reachable.
+#if __has_builtin(__builtin_unreachable) || defined(__GNUC__)
+#define ORC_RT_BUILTIN_UNREACHABLE __builtin_unreachable()
+#elif defined(_MSC_VER)
+#define ORC_RT_BUILTIN_UNREACHABLE __assume(false)
+#else
+#define ORC_RT_BUILTIN_UNREACHABLE
+#endif
+
+// ORC_RT_UNREACHABLE(MSG): marks a point the program must never reach. In
+// +Asserts builds it aborts with MSG; otherwise it lowers to
+// ORC_RT_BUILTIN_UNREACHABLE.
+#ifndef NDEBUG
+#define ORC_RT_UNREACHABLE(MSG)                                                \
+  do {                                                                         \
+    assert(false && (MSG));                                                    \
+    ORC_RT_BUILTIN_UNREACHABLE;                                                \
+  } while (false)
+#else
+#define ORC_RT_UNREACHABLE(MSG) ORC_RT_BUILTIN_UNREACHABLE
+#endif
+
 #endif // ORC_RT_COMPILER_H
diff --git a/orc-rt/test/unit/CMakeLists.txt b/orc-rt/test/unit/CMakeLists.txt
index 3a39a6d7c8d7d..db83ece1f4edb 100644
--- a/orc-rt/test/unit/CMakeLists.txt
+++ b/orc-rt/test/unit/CMakeLists.txt
@@ -17,6 +17,7 @@ add_orc_rt_unittest(CoreTests
   BootstrapInfoTest.cpp
   CallSPSCITest.cpp
   CallableTraitsHelperTest.cpp
+  CompilerTest.cpp
   SimpleSymbolTableTest.cpp
   EndianTest.cpp
   ErrorCAPITest.cpp
diff --git a/orc-rt/test/unit/CompilerTest.cpp b/orc-rt/test/unit/CompilerTest.cpp
new file mode 100644
index 0000000000000..9a610ffc8217c
--- /dev/null
+++ b/orc-rt/test/unit/CompilerTest.cpp
@@ -0,0 +1,43 @@
+//===- CompilerTest.cpp ---------------------------------------------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+//
+// Tests for the utilities in orc-rt/Compiler.h.
+//
+//===----------------------------------------------------------------------===//
+
+#include "orc-rt/Compiler.h"
+
+#include "gtest/gtest.h"
+
+namespace {
+
+int reachablePathReturns(int X) {
+  switch (X) {
+  case 0:
+    return 0;
+  default:
+    ORC_RT_UNREACHABLE("only 0 is expected");
+  }
+}
+
+} // anonymous namespace
+
+TEST(CompilerTest, UnreachableCompilesInReturningFunction) {
+  EXPECT_EQ(reachablePathReturns(0), 0);
+}
+
+// ORC_RT_UNREACHABLE only aborts in +Asserts builds; under NDEBUG it lowers to
+// a bare optimizer hint whose execution is undefined behavior, so there is
+// nothing well-defined to assert on in a release build. Test for !NDEBUG builds
+// only.
+#ifndef NDEBUG
+TEST(CompilerDeathTest, UnreachableAborts) {
+  EXPECT_DEATH(ORC_RT_UNREACHABLE("unreachable reached"),
+               "unreachable reached");
+}
+#endif