From 2915519efd9185bf06dd09a50a853e9945198983 Mon Sep 17 00:00:00 2001
From: Lang Hames <lhames@gmail.com>
Date: Wed, 18 Mar 2026 22:17:04 +1100
Subject: [PATCH] [orc-rt] Move CallViaSession into Session, add comments.
 (#187238)

Makes CallViaSession an inner class on Session, and adds comments and a
convenience method for creating instances.
---
 orc-rt/include/orc-rt/Session.h  | 43 +++++++++++++++++++++-----------
 orc-rt/unittests/SessionTest.cpp |  6 ++---
 2 files changed, 32 insertions(+), 17 deletions(-)

diff --git a/orc-rt/include/orc-rt/Session.h b/orc-rt/include/orc-rt/Session.h
index 9d64afaee8f2..287ff7ea0777 100644
--- a/orc-rt/include/orc-rt/Session.h
+++ b/orc-rt/include/orc-rt/Session.h
@@ -171,6 +171,11 @@ public:
   /// Disconnect the ControllerAccess object.
   void detach();
 
+  /// Call a tagged handler in the Controller.
+  ///
+  /// This method can be called directly, but is expected to be more commonly
+  /// called by the WrapperFunction::call method using a CallViaSession object
+  /// (see below).
   void callController(OnCallHandlerCompleteFn OnComplete, HandlerTag T,
                       WrapperFunctionBuffer ArgBytes) {
     if (auto TmpCA = CA)
@@ -180,6 +185,30 @@ public:
           "no controller attached"));
   }
 
+  /// Provides an async method interface to call, via the given Session, the
+  /// controller handler with the given tag.
+  ///
+  /// Useable as a Caller implementation with WrapperFunction::call.
+  class CallViaSession {
+  public:
+    CallViaSession(Session &S, HandlerTag T) : S(S), T(T) {}
+
+    void operator()(OnCallHandlerCompleteFn &&HandleResult,
+                    WrapperFunctionBuffer ArgBytes) {
+      S.callController(std::move(HandleResult), T, std::move(ArgBytes));
+    }
+
+  private:
+    Session &S;
+    HandlerTag T;
+  };
+
+  /// Get a WrapperFunction::call-compatible Caller that will call through to
+  /// the handler with the given tag.
+  CallViaSession callViaSession(HandlerTag T) noexcept {
+    return CallViaSession(*this, T);
+  }
+
 private:
   struct ShutdownInfo {
     bool Complete = false;
@@ -215,20 +244,6 @@ private:
   std::unique_ptr<ShutdownInfo> SI;
 };
 
-class CallViaSession {
-public:
-  CallViaSession(Session &S, Session::HandlerTag T) : S(S), T(T) {}
-
-  void operator()(Session::OnCallHandlerCompleteFn &&HandleResult,
-                  WrapperFunctionBuffer ArgBytes) {
-    S.callController(std::move(HandleResult), T, std::move(ArgBytes));
-  }
-
-private:
-  Session &S;
-  Session::HandlerTag T;
-};
-
 } // namespace orc_rt
 
 #endif // ORC_RT_SESSION_H
diff --git a/orc-rt/unittests/SessionTest.cpp b/orc-rt/unittests/SessionTest.cpp
index f131ccb61c2a..fd873c5e8146 100644
--- a/orc-rt/unittests/SessionTest.cpp
+++ b/orc-rt/unittests/SessionTest.cpp
@@ -420,7 +420,7 @@ TEST(ControllerAccessTest, ValidCallToController) {
 
   int32_t Result = 0;
   SPSWrapperFunction<int32_t(int32_t, int32_t)>::call(
-      CallViaSession(S, reinterpret_cast<Session::HandlerTag>(add_sps_wrapper)),
+      S.callViaSession(reinterpret_cast<Session::HandlerTag>(add_sps_wrapper)),
       [&](Expected<int32_t> R) { Result = cantFail(std::move(R)); }, 41, 1);
 
   EnqueueingDispatcher::runTasksFromFront(Tasks);
@@ -438,7 +438,7 @@ TEST(ControllerAccessTest, CallToControllerBeforeAttach) {
 
   Error Err = Error::success();
   SPSWrapperFunction<int32_t(int32_t, int32_t)>::call(
-      CallViaSession(S, reinterpret_cast<Session::HandlerTag>(add_sps_wrapper)),
+      S.callViaSession(reinterpret_cast<Session::HandlerTag>(add_sps_wrapper)),
       [&](Expected<int32_t> R) {
         ErrorAsOutParameter _(Err);
         Err = R.takeError();
@@ -462,7 +462,7 @@ TEST(ControllerAccessTest, CallToControllerAfterDetach) {
 
   Error Err = Error::success();
   SPSWrapperFunction<int32_t(int32_t, int32_t)>::call(
-      CallViaSession(S, reinterpret_cast<Session::HandlerTag>(add_sps_wrapper)),
+      S.callViaSession(reinterpret_cast<Session::HandlerTag>(add_sps_wrapper)),
       [&](Expected<int32_t> R) {
         ErrorAsOutParameter _(Err);
         Err = R.takeError();