[llvm] [orc-rt] Add Session instance symbols, SPS CI to look them up (PR #231043)
Lang Hames via llvm-commits
llvm-commits at lists.llvm.org
Sun Oct 11 15:27:01 PDT 2026
https://github.com/lhames updated https://github.com/llvm/llvm-project/pull/231043
>From 87f0e07c4a422724361845ad4d352e8a11eafaaf Mon Sep 17 00:00:00 2001
From: Lang Hames <lhames at gmail.com>
Date: Sun, 11 Oct 2026 17:20:25 +1100
Subject: [PATCH] [orc-rt] Add Session instance symbols, SPS CI to look them up
Objects created at runtime (e.g. service instances) have no symbols
under the standard object models, so the controller has no way to find
them by name. Instance symbols fill that gap:
Session::addInstanceSymbols registers (name, address) pairs for such
objects, and Session::lookupInstanceSymbols resolves a SymbolLookupSet
against them, with the same missing-symbol semantics as
SimpleSymbolTable::lookup. Duplicate handling follows
SimpleSymbolTable::addUnique: a batch containing a conflicting
definition is rejected as a whole.
The new orc_rt_ci_sps_Session_lookupInstanceSymbols wrapper exposes the
lookup to the controller. It is registered by sps_ci::addSession, which
sps_ci::addAll now includes.
---
orc-rt/include/orc-rt/bedrock/Session.h | 32 +++++
.../include/orc-rt/bedrock/sps/SessionSPSCI.h | 28 +++++
orc-rt/lib/bedrock/CMakeLists.txt | 1 +
orc-rt/lib/bedrock/Session.cpp | 6 +
orc-rt/lib/bedrock/sps/AllSPSCI.cpp | 2 +
orc-rt/lib/bedrock/sps/SessionSPSCI.cpp | 70 +++++++++++
orc-rt/test/unit/CMakeLists.txt | 1 +
.../test/unit/bedrock/BootstrapInfoTest.cpp | 8 ++
orc-rt/test/unit/bedrock/SessionTest.cpp | 45 +++++++
.../unit/bedrock/sps/SessionSPSCITest.cpp | 117 ++++++++++++++++++
10 files changed, 310 insertions(+)
create mode 100644 orc-rt/include/orc-rt/bedrock/sps/SessionSPSCI.h
create mode 100644 orc-rt/lib/bedrock/sps/SessionSPSCI.cpp
create mode 100644 orc-rt/test/unit/bedrock/sps/SessionSPSCITest.cpp
diff --git a/orc-rt/include/orc-rt/bedrock/Session.h b/orc-rt/include/orc-rt/bedrock/Session.h
index efb4cd9783d6c..10409d828b5b5 100644
--- a/orc-rt/include/orc-rt/bedrock/Session.h
+++ b/orc-rt/include/orc-rt/bedrock/Session.h
@@ -20,6 +20,7 @@
#include "orc-rt/bedrock/TaskGroup.h"
#include "orc-rt/support/Error.h"
#include "orc-rt/support/LockedAccess.h"
+#include "orc-rt/support/SymbolLookupSet.h"
#include "orc-rt/support/WrapperFunction.h"
#include "orc-rt/support/move_only_function.h"
@@ -401,6 +402,36 @@ class Session {
this->OnDisconnect = std::move(OnDisconnect);
}
+ /// Add instance symbols to the Session.
+ ///
+ /// Instance symbols name objects created at runtime (e.g. service
+ /// instances). Such objects have no symbols under the standard object
+ /// models, so instance symbols give them names that can be looked up (see
+ /// lookupInstanceSymbols) and linked against.
+ ///
+ /// NewSymbols may be a range of (SymbolNameSpec, address) pairs, or an
+ /// rvalue SimpleSymbolTable. Names are mangled as they're added (see
+ /// SymbolNameSpec), so lookups must use the resulting linker-level names.
+ ///
+ /// Duplicate handling follows SimpleSymbolTable::addUnique: re-adding an
+ /// existing (name, address) pair is allowed, but if any name in NewSymbols
+ /// is already registered with a different address then an error is
+ /// returned and none of NewSymbols are added.
+ template <typename SymbolRangeT>
+ Error addInstanceSymbols(SymbolRangeT &&NewSymbols) noexcept {
+ std::scoped_lock<std::mutex> Lock(M);
+ return InstanceSymbols.addUnique(std::forward<SymbolRangeT>(NewSymbols));
+ }
+
+ /// Look up instance symbols, returning one result per element of LS, in
+ /// the same order. Names are linker-level and used as written.
+ ///
+ /// Missing symbols are reported as described by SymbolLookupResult: a missing
+ /// weakly referenced symbol yields a null address, and a missing required
+ /// symbol yields an empty optional.
+ SymbolLookupResult
+ lookupInstanceSymbols(const SymbolLookupSet &LS) const noexcept;
+
/// Add a Service to the session.
template <typename ServiceT>
ServiceT &addService(std::unique_ptr<ServiceT> Srv) {
@@ -764,6 +795,7 @@ class Session {
std::condition_variable CV;
State CurrentState = State::Start;
State TargetState = State::None;
+ SimpleSymbolTable InstanceSymbols;
std::vector<std::unique_ptr<Service>> Services;
NotificationService &Notifiers;
};
diff --git a/orc-rt/include/orc-rt/bedrock/sps/SessionSPSCI.h b/orc-rt/include/orc-rt/bedrock/sps/SessionSPSCI.h
new file mode 100644
index 0000000000000..9c2a08730b923
--- /dev/null
+++ b/orc-rt/include/orc-rt/bedrock/sps/SessionSPSCI.h
@@ -0,0 +1,28 @@
+//===-------------- SessionSPSCI.h - Session SPS CI -------------*- C++ -*-===//
+//
+// 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
+//
+//===----------------------------------------------------------------------===//
+//
+// SPS Controller Interface registration for Session APIs.
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef ORC_RT_BEDROCK_SPS_SESSIONSPSCI_H
+#define ORC_RT_BEDROCK_SPS_SESSIONSPSCI_H
+
+#include "orc-rt/bedrock/SimpleSymbolTable.h"
+#include "orc-rt/support/sps/SPSWrapperFunction.h"
+
+ORC_RT_SPS_WRAPPER_DECL(orc_rt_ci_sps_Session_lookupInstanceSymbols)
+
+namespace orc_rt::sps_ci {
+
+/// Add the SPS controller interface to the Session APIs.
+Error addSession(SimpleSymbolTable &ST) noexcept;
+
+} // namespace orc_rt::sps_ci
+
+#endif // ORC_RT_BEDROCK_SPS_SESSIONSPSCI_H
diff --git a/orc-rt/lib/bedrock/CMakeLists.txt b/orc-rt/lib/bedrock/CMakeLists.txt
index b2236a54e82cf..9f50333822cb2 100644
--- a/orc-rt/lib/bedrock/CMakeLists.txt
+++ b/orc-rt/lib/bedrock/CMakeLists.txt
@@ -17,6 +17,7 @@ set(ORC_RT_BEDROCK_SOURCES
sps/GDBJITRegistrarSPSCI.cpp
sps/MemoryAccessSPSCI.cpp
sps/NativeDylibManagerSPSCI.cpp
+ sps/SessionSPSCI.cpp
sps/SimpleNativeMemoryMapSPSCI.cpp
sps/SimpleRemoteCA.cpp
)
diff --git a/orc-rt/lib/bedrock/Session.cpp b/orc-rt/lib/bedrock/Session.cpp
index 457b1ea5b384f..a2940c0711097 100644
--- a/orc-rt/lib/bedrock/Session.cpp
+++ b/orc-rt/lib/bedrock/Session.cpp
@@ -71,6 +71,12 @@ Session::~Session() {
ORC_RT_LOG(Info, Session, "Session %p destructor complete", this);
}
+SymbolLookupResult
+Session::lookupInstanceSymbols(const SymbolLookupSet &LS) const noexcept {
+ std::scoped_lock<std::mutex> Lock(M);
+ return InstanceSymbols.lookup(LS);
+}
+
void Session::doAttach(std::shared_ptr<ControllerAccess> CA, BootstrapInfo BI) {
assert(CA && "doAttach called with null CA object");
diff --git a/orc-rt/lib/bedrock/sps/AllSPSCI.cpp b/orc-rt/lib/bedrock/sps/AllSPSCI.cpp
index 9a9b43ad62e87..529d50696b4c0 100644
--- a/orc-rt/lib/bedrock/sps/AllSPSCI.cpp
+++ b/orc-rt/lib/bedrock/sps/AllSPSCI.cpp
@@ -16,6 +16,7 @@
#include "orc-rt/bedrock/sps/GDBJITRegistrarSPSCI.h"
#include "orc-rt/bedrock/sps/MemoryAccessSPSCI.h"
#include "orc-rt/bedrock/sps/NativeDylibManagerSPSCI.h"
+#include "orc-rt/bedrock/sps/SessionSPSCI.h"
#include "orc-rt/bedrock/sps/SimpleNativeMemoryMapSPSCI.h"
#include "orc-rt/bedrock/sps/StandaloneMachOUnwindInfoRegistrarSPSCI.h"
@@ -28,6 +29,7 @@ Error addAll(SimpleSymbolTable &ST) {
addGDBJITRegistrar,
addMemoryAccess,
addNativeDylibManager,
+ addSession,
addSimpleNativeMemoryMap,
#if defined(__APPLE__)
// DWARFEHFrameRegistrar is also built on Darwin, but
diff --git a/orc-rt/lib/bedrock/sps/SessionSPSCI.cpp b/orc-rt/lib/bedrock/sps/SessionSPSCI.cpp
new file mode 100644
index 0000000000000..4f62c858480b0
--- /dev/null
+++ b/orc-rt/lib/bedrock/sps/SessionSPSCI.cpp
@@ -0,0 +1,70 @@
+//===- SessionSPSCI.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
+//
+//===----------------------------------------------------------------------===//
+//
+// SPS Controller Interface implementation for Session APIs.
+//
+//===----------------------------------------------------------------------===//
+
+#include "orc-rt/bedrock/sps/SessionSPSCI.h"
+
+#include "orc-rt/bedrock/Session.h"
+#include "orc-rt/support/move_only_function.h"
+#include "orc-rt/support/sps/SPSSymbolLookupSet.h"
+
+// Wrapper for Session methods that uses the wrapper's Session argument.
+#define ORC_RT_SPS_SESSION_WRAPPER_IMPL(Name, SPSSig, HandlerBuilder) \
+ ORC_RT_SPS_WRAPPER_DECL(Name) \
+ extern "C" ORC_RT_SPS_WRAPPER_SIG(Name) { \
+ orc_rt::SPSWrapperFunction<SPSSig>::handle(S, ArgBytes, Return, CallId, \
+ (HandlerBuilder)(S)); \
+ }
+
+namespace orc_rt::sps_ci {
+
+namespace {
+
+template <typename RetT, typename... ArgTs> class SessionSyncMethod {
+public:
+ SessionSyncMethod(RetT (Session::*M)(ArgTs...) const noexcept) noexcept
+ : M(M) {}
+
+ // Not a handler, but a handler-builder: This is the HandlerBuilder function
+ // used in the macro above -- it takes a Session and returns a wrapper to be
+ // used in the WrapperFunction::handle method.
+ auto operator()(orc_rt_SessionRef S) noexcept {
+ assert(S && "Session pointer must not be null");
+ return [S, M = M](move_only_function<void(RetT)> Return,
+ ArgTs &&...Args) noexcept {
+ Return((unwrap(S)->*M)(std::forward<ArgTs>(Args)...));
+ };
+ }
+
+private:
+ RetT (Session::*M)(ArgTs...) const noexcept;
+};
+
+template <typename RetT, typename... ArgTs>
+SessionSyncMethod(RetT (Session::*M)(ArgTs...) const noexcept)
+ -> SessionSyncMethod<RetT, ArgTs...>;
+
+} // namespace
+
+ORC_RT_SPS_SESSION_WRAPPER_IMPL(
+ orc_rt_ci_sps_Session_lookupInstanceSymbols,
+ SPSSymbolLookupResult(SPSSymbolLookupSet),
+ SessionSyncMethod(&Session::lookupInstanceSymbols))
+
+static std::pair<SymbolNameSpec, const void *>
+ orc_rt_ci_Session_sps_interface[] = {
+ ORC_RT_SYMTAB_C_PAIR(orc_rt_ci_sps_Session_lookupInstanceSymbols)};
+
+Error addSession(SimpleSymbolTable &ST) noexcept {
+ return ST.addUnique(orc_rt_ci_Session_sps_interface);
+}
+
+} // namespace orc_rt::sps_ci
diff --git a/orc-rt/test/unit/CMakeLists.txt b/orc-rt/test/unit/CMakeLists.txt
index 82df7bacc704f..f84aac6936688 100644
--- a/orc-rt/test/unit/CMakeLists.txt
+++ b/orc-rt/test/unit/CMakeLists.txt
@@ -132,6 +132,7 @@ add_orc_rt_unittest(BedrockTests
bedrock/sps/CallSPSCITest.cpp
bedrock/sps/MemoryAccessSPSCITest.cpp
bedrock/sps/NativeDylibManagerSPSCITest.cpp
+ bedrock/sps/SessionSPSCITest.cpp
bedrock/sps/SimpleNativeMemoryMapSPSCITest.cpp
bedrock/sps/SimpleRemoteCATest.cpp
diff --git a/orc-rt/test/unit/bedrock/BootstrapInfoTest.cpp b/orc-rt/test/unit/bedrock/BootstrapInfoTest.cpp
index a4cc4f77406d2..995873461bc4f 100644
--- a/orc-rt/test/unit/bedrock/BootstrapInfoTest.cpp
+++ b/orc-rt/test/unit/bedrock/BootstrapInfoTest.cpp
@@ -82,6 +82,14 @@ TEST(BootstrapInfoTest, CreateDefaultContainsSPSCISymbols) {
SymbolNameSpec::c("orc_rt_ci_sps_SimpleNativeMemoryMap_reserve")));
}
+TEST(BootstrapInfoTest, CreateDefaultContainsSessionSPSCISymbols) {
+ Session S(mockExecutorProcessInfo(), noDispatch, noErrors);
+ auto BI = BootstrapInfo::CreateDefault(S);
+ ASSERT_THAT_EXPECTED(BI, Succeeded());
+ EXPECT_TRUE(BI->symbols().count(
+ SymbolNameSpec::c("orc_rt_ci_sps_Session_lookupInstanceSymbols")));
+}
+
TEST(BootstrapInfoTest, CreateDefaultWithNoSymbolsBuilder) {
Session S(mockExecutorProcessInfo(), noDispatch, noErrors);
auto BI = BootstrapInfo::CreateDefault(S, /*AddInitialSymbols=*/{},
diff --git a/orc-rt/test/unit/bedrock/SessionTest.cpp b/orc-rt/test/unit/bedrock/SessionTest.cpp
index 7f75f44dd4fdc..c88d4330d6924 100644
--- a/orc-rt/test/unit/bedrock/SessionTest.cpp
+++ b/orc-rt/test/unit/bedrock/SessionTest.cpp
@@ -621,6 +621,51 @@ TEST(SessionTest, TryCreateServiceFailure) {
EXPECT_THAT_EXPECTED(S.tryCreateService<ConfigurableService>(true), Failed());
}
+TEST(SessionTest, InstanceSymbolsAddAndLookup) {
+ Session S(mockExecutorProcessInfo(), noDispatch, noErrors);
+ int Foo = 0, Bar = 0;
+
+ // Add Foo from a range of pairs, and Bar from a SimpleSymbolTable.
+ std::pair<SymbolNameSpec, const void *> FooEntry[] = {
+ {SymbolNameSpec::linker("orc_rt_test_Foo"), &Foo}};
+ ASSERT_THAT_ERROR(S.addInstanceSymbols(FooEntry), Succeeded());
+
+ SimpleSymbolTable BarTable;
+ std::pair<SymbolNameSpec, const void *> BarEntry[] = {
+ {SymbolNameSpec::linker("orc_rt_test_Bar"), &Bar}};
+ ASSERT_THAT_ERROR(BarTable.addUnique(BarEntry), Succeeded());
+ ASSERT_THAT_ERROR(S.addInstanceSymbols(std::move(BarTable)), Succeeded());
+
+ auto Addrs = S.lookupInstanceSymbols(
+ {{"orc_rt_test_Foo", SymbolLookupFlags::RequiredSymbol},
+ {"orc_rt_test_Bar", SymbolLookupFlags::RequiredSymbol}});
+ ASSERT_EQ(Addrs.size(), 2U);
+ EXPECT_THAT(Addrs[0], Optional(Eq(&Foo)));
+ EXPECT_THAT(Addrs[1], Optional(Eq(&Bar)));
+}
+
+TEST(SessionTest, InstanceSymbolsConflictingAddFails) {
+ Session S(mockExecutorProcessInfo(), noDispatch, noErrors);
+ int Foo = 0, OtherFoo = 0, Bar = 0;
+ std::pair<SymbolNameSpec, const void *> FooEntry[] = {
+ {SymbolNameSpec::linker("orc_rt_test_Foo"), &Foo}};
+ ASSERT_THAT_ERROR(S.addInstanceSymbols(FooEntry), Succeeded());
+
+ // A batch containing one conflicting definition should be rejected as a
+ // whole: neither the conflicting Foo nor the otherwise-valid Bar is added.
+ std::pair<SymbolNameSpec, const void *> Batch[] = {
+ {SymbolNameSpec::linker("orc_rt_test_Foo"), &OtherFoo},
+ {SymbolNameSpec::linker("orc_rt_test_Bar"), &Bar}};
+ EXPECT_THAT_ERROR(S.addInstanceSymbols(Batch), Failed());
+
+ auto Addrs = S.lookupInstanceSymbols(
+ {{"orc_rt_test_Foo", SymbolLookupFlags::RequiredSymbol},
+ {"orc_rt_test_Bar", SymbolLookupFlags::RequiredSymbol}});
+ ASSERT_EQ(Addrs.size(), 2U);
+ EXPECT_THAT(Addrs[0], Optional(Eq(&Foo)));
+ EXPECT_FALSE(Addrs[1].has_value());
+}
+
TEST(ControllerAccessTest, Basics) {
// Test that we can set the ControllerAccess implementation and still shut
// down as expected.
diff --git a/orc-rt/test/unit/bedrock/sps/SessionSPSCITest.cpp b/orc-rt/test/unit/bedrock/sps/SessionSPSCITest.cpp
new file mode 100644
index 0000000000000..a689dc1d3aafd
--- /dev/null
+++ b/orc-rt/test/unit/bedrock/sps/SessionSPSCITest.cpp
@@ -0,0 +1,117 @@
+//===- SessionSPSCITest.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 Session's SPS Controller Interface.
+//
+//===----------------------------------------------------------------------===//
+
+#include "orc-rt/bedrock/sps/SessionSPSCI.h"
+#include "orc-rt/bedrock/Session.h"
+#include "orc-rt/support/sps/SPSSymbolLookupSet.h"
+#include "orc-rt/support/sps/SPSWrapperFunction.h"
+
+#include "BedrockTestUtils.h"
+#include "CommonTestUtils.h"
+#include "DirectCaller.h"
+#include "ErrorMatchers.h"
+#include "gtest/gtest.h"
+
+#include <future>
+
+using namespace orc_rt;
+using namespace orc_rt::test;
+
+namespace {
+// Local aliases for brevity in test bodies.
+constexpr auto Req = SymbolLookupFlags::RequiredSymbol;
+constexpr auto Weak = SymbolLookupFlags::WeaklyReferencedSymbol;
+} // namespace
+
+class SessionSPSCITest : public ::testing::Test {
+protected:
+ void SetUp() override {
+ S = std::make_unique<Session>(mockExecutorProcessInfo(), noDispatch,
+ noErrors);
+ ASSERT_THAT_ERROR(sps_ci::addSession(CI), Succeeded());
+
+ // Instance symbols are keyed by linker-level name, so register them with
+ // SymbolNameSpec::linker to keep the lookup names platform-independent.
+ std::pair<SymbolNameSpec, const void *> Entries[] = {
+ {SymbolNameSpec::linker("orc_rt_test_Foo"), &Foo},
+ {SymbolNameSpec::linker("orc_rt_test_Bar"), &Bar}};
+ ASSERT_THAT_ERROR(S->addInstanceSymbols(Entries), Succeeded());
+ }
+
+ Expected<SymbolLookupResult> spsLookup(SymbolLookupSet Symbols) {
+ using SPSSig = SPSSymbolLookupResult(SPSSymbolLookupSet);
+ std::future<Expected<SymbolLookupResult>> Result;
+ SPSWrapperFunction<SPSSig>::call(
+ caller(orc_rt_ci_sps_Session_lookupInstanceSymbols), waitFor(Result),
+ std::move(Symbols));
+ return Result.get();
+ }
+
+ DirectCaller caller(orc_rt_WrapperFunction Fn) { return {wrap(S.get()), Fn}; }
+
+ int Foo = 0;
+ int Bar = 0;
+ SimpleSymbolTable CI;
+ std::unique_ptr<Session> S;
+};
+
+TEST_F(SessionSPSCITest, Registration) {
+ EXPECT_TRUE(CI.count(
+ SymbolNameSpec::c("orc_rt_ci_sps_Session_lookupInstanceSymbols")));
+}
+
+TEST_F(SessionSPSCITest, LookupRegisteredSymbol) {
+ auto Addrs = spsLookup({{"orc_rt_test_Foo", Req}});
+ ASSERT_THAT_EXPECTED(Addrs, Succeeded());
+ ASSERT_EQ(Addrs->size(), 1U);
+ ASSERT_TRUE((*Addrs)[0].has_value());
+ EXPECT_EQ(*(*Addrs)[0], &Foo);
+}
+
+TEST_F(SessionSPSCITest, LookupMissingRequiredSymbol) {
+ auto Addrs = spsLookup({{"orc_rt_test_Missing", Req}});
+ ASSERT_THAT_EXPECTED(Addrs, Succeeded());
+ ASSERT_EQ(Addrs->size(), 1U);
+ EXPECT_FALSE((*Addrs)[0].has_value())
+ << "required-missing symbol should be reported as an empty optional";
+}
+
+TEST_F(SessionSPSCITest, LookupMissingWeakSymbol) {
+ auto Addrs = spsLookup({{"orc_rt_test_Missing", Weak}});
+ ASSERT_THAT_EXPECTED(Addrs, Succeeded());
+ ASSERT_EQ(Addrs->size(), 1U);
+ ASSERT_TRUE((*Addrs)[0].has_value())
+ << "weak-missing symbol should be reported as a present optional";
+ EXPECT_EQ(*(*Addrs)[0], nullptr);
+}
+
+TEST_F(SessionSPSCITest, LookupMixedSetPreservesOrder) {
+ auto Addrs = spsLookup({{"orc_rt_test_Bar", Req},
+ {"orc_rt_test_Missing", Req},
+ {"orc_rt_test_Foo", Weak},
+ {"orc_rt_test_Missing", Weak}});
+ ASSERT_THAT_EXPECTED(Addrs, Succeeded());
+ ASSERT_EQ(Addrs->size(), 4U);
+ ASSERT_TRUE((*Addrs)[0].has_value());
+ EXPECT_EQ(*(*Addrs)[0], &Bar);
+ EXPECT_FALSE((*Addrs)[1].has_value());
+ ASSERT_TRUE((*Addrs)[2].has_value());
+ EXPECT_EQ(*(*Addrs)[2], &Foo);
+ ASSERT_TRUE((*Addrs)[3].has_value());
+ EXPECT_EQ(*(*Addrs)[3], nullptr);
+}
+
+TEST_F(SessionSPSCITest, LookupEmptySet) {
+ auto Addrs = spsLookup({});
+ ASSERT_THAT_EXPECTED(Addrs, Succeeded());
+ EXPECT_TRUE(Addrs->empty());
+}
More information about the llvm-commits
mailing list