[orc-rt] Update Session shutdown sequence docs / comments. (#190783)

Clarify Session lifecycle contract docs across Service.h, Session.h, and
Design.md, and update to reflect the introduction of the
ManagedCallsTaskGroup (543ec358dd).

orc-rt/docs/Design.md

@@ -55,12 +55,17 @@ controller and can make no further calls to the controller.
 `Service` is an interface for classes that provide services to the Session.
 E.g. memory managers, or dynamic library loaders.
 
-The `Service` interface provides two operations: `detach` and `shutdown`. The
-`shutdown` operation will be called at `Session` destruction time. The `detach`
-operation will be called if the controller detaches. Since this means that no
-further requests for service will be made by the controller, Services may
-implement this operation to abandon any fine-grained book-keeping that is
-needed to provide ongoing services to the controller.
+The `Service` interface provides two operations: `onDetach` and `onShutdown`.
+`onDetach` signals that controller access is permanently unavailable. It is
+always called before `onShutdown`, regardless of how the Session reaches
+shutdown -- including when no controller was ever attached. Since no further
+requests will be made by the controller after `onDetach`, Services may use it
+to abandon any fine-grained book-keeping that is only needed to service
+controller requests. Many Services will implement `onDetach` as a no-op.
+
+The `onShutdown` operation will be called at `Session` destruction time, after
+all in-flight managed code calls have completed. Services should release all
+held resources during `onShutdown`.
 
 ### TaskDispatcher
 

orc-rt/include/orc-rt/Service.h

@@ -28,11 +28,15 @@ public:
 
   virtual ~Service();
 
-  /// The onDetach method will be called when the controller disconnects from
-  /// the session (or if the Session is shut down without a controller ever
-  /// being attached).
+  /// Called when controller access becomes permanently unavailable.
   ///
-  /// Once onDetach is called no further requests will be made to the Service
+  /// This is guaranteed to be called exactly once before onShutdown,
+  /// regardless of how the Session reaches that state. It is called when:
+  ///   - The controller explicitly disconnects.
+  ///   - The Session::detach() method is called.
+  ///   - The Session shuts down (even if no controller was ever attached).
+  ///
+  /// After onDetach is called no further requests will be made to the Service
   /// by the controller. Note that JIT'd code may continue to make requests to
   /// the service concurrent with a call to onDetach.
   ///

orc-rt/include/orc-rt/Session.h

@@ -272,9 +272,12 @@ public:
 
   /// Initiate detach from the controller.
   ///
-  /// If attached, this will request disconnection from the controller and
-  /// then notify all Services via onDetach. The optional OnDetach callback
-  /// will be called once the detach is complete.
+  /// Signals that controller access is permanently unavailable and notifies
+  /// all Services via onDetach. If a controller is attached, this will
+  /// request disconnection first.
+  ///
+  /// The optional OnDetach callback will be called once the detach is
+  /// complete.
   ///
   /// If the Session is already detached or shut down, the callback (if
   /// provided) will be called immediately.
@@ -282,7 +285,17 @@ public:
 
   /// Initiate session shutdown.
   ///
-  /// Runs shutdown on registered resources in reverse order.
+  /// Shutdown proceeds through the following phases:
+  ///   1. Detach: If not already detached, disconnects the controller and
+  ///      notifies all Services via onDetach.
+  ///   2. Drain: Waits for all in-flight managed code calls to complete
+  ///      (via ManagedCodeCallsGroup).
+  ///   3. Shutdown services: Calls onShutdown on all Services in reverse
+  ///      order.
+  ///   4. Shutdown TaskDispatcher.
+  ///
+  /// The optional OnShutdown callback is called after step (3), before
+  /// the TaskDispatcher is shut down.
   void shutdown(OnShutdownFn OnShutdown = {});
 
   /// Initiate session shutdown and block until complete.