From 96bf3d1dd67a731e1c061e0d1d15324bca435a5f Mon Sep 17 00:00:00 2001 From: Joshua Hursey Date: Thu, 5 Aug 2021 10:07:54 -0500 Subject: [PATCH] Use Case: Cross-Version Support * A use case the details the cross-version compatability needs of a PMIx implementation. Signed-off-by: Joshua Hursey --- App_Use_Cases.tex | 88 +++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 86 insertions(+), 2 deletions(-) diff --git a/App_Use_Cases.tex b/App_Use_Cases.tex index 5c284d4d..50ee0514 100644 --- a/App_Use_Cases.tex +++ b/App_Use_Cases.tex @@ -10,7 +10,7 @@ \chapter{Use-Cases} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\section {Business Card Exchange for Process-to-Process Wire-up} +\section{Business Card Exchange for Process-to-Process Wire-up} \label{app:uc-business-card-exchange} \subsection{Use Case Summary} @@ -82,6 +82,8 @@ \subsection{Use Case Details} There are other keys that are helpful to have before a synchronization point. This is not meant to be a comprehensive list. +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Debugging} \label{app:uc-debugging} @@ -319,6 +321,8 @@ \subsubsection{Environmental Parameter Directives for Applications and Launchers Resource managers and launchers must scan for relevant directives, modifying environmental parameters as directed. Directives are to be processed in the order in which they were given, starting with job-level directives (applied to each app) followed by app-level directives. +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Hybrid Applications} \label{app:uc-hybrid-applications} @@ -448,6 +452,8 @@ \subsubsection{Coordinating at Runtime with Multiple Event Handlers} \refconst{PMIX_EVENT_PARTIAL_ACTION_TAKEN} \\ \refconst{PMIX_EVENT_ACTION_DEFERRED} \\ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{MPI Sessions} \label{app:uc-MPI-sessions} @@ -502,7 +508,85 @@ \subsection{Use Case Details} \littleheader{Related Constants} -\refconst{PMIX_SUCCESS} +\refconst{PMIX_SUCCESS}\\ \refconst{PMIX_ERR_NOT_SUPPORTED} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\section{Cross-Version Compatability} +\label{app:uc-cross-version} + +\subsection{Use Case Summary} + +The \ac{PMIx} interface serves as a conduit between clients (e.g., \ac{MPI} libraries), tools (e.g., debuggers), and servers (e.g., \acp{RM}). +As such, it is probable that a process operating in one of these roles (e.g., as a client or tool) is running a different version of the same \ac{PMIx} implementation than the process with which it is communicating that is operating in a different role (e.g., as a server). +For processes running in containers cross-version compatibility is especially important because the container image and the system software levels will naturally evolve and drift apart. +As such, there is a need for the \ac{PMIx} implementation to provide cross-version compatibility. + +The responsibility for providing cross-version compatibility is a feature of the \ac{PMIx} implementation and not necessarily of the \ac{PMIx} standard. +The \ac{PMIx} standard must strive to enable, and never limit, both the cross-version compatibility in the \ac{PMIx} implementation, and the ability for a \ac{PMIx} consumer to adapt to cross-version differences in capabilities. + +This use case is focused on cross-version compatibility between versions of the same \ac{PMIx} implementation and not between different \ac{PMIx} implementations. + +Cross-version compatibility responsibilities are not restricted to \ac{PMIx}, but a general issue for any library that coordinates across multiple processes. This includes, but not limited to, client/server libraries, and libraries with a user-space and kernel-space component (e.g., high-performance interconnect libraries). + +\subsection{Use Case Details} + +There are three scenarios that a \ac{PMIx} implementation and a \ac{PMIx} consumer must consider. +These scenarios use a PMIx Server and a PMIx Client for clarity, though the scenarios also apply to PMIx Tools. +\begin{enumerate} +\item \textbf{PMIx Server version matches PMIx Client version}: +No cross-version considerations are necessary since they are running the same version. +\item \textbf{PMIx Server version is older than PMIx Client version}: +The implementation must negotiate capabilities during the initial handshake.\\ +This scenario is common if the (possibly containerized) PMIx client application is being run on an established system that does not update as frequently as the application requires. +Thus the PMIx Server in the \ac{RM} is locked to an older version of the \ac{PMIx} implementation. +\item \textbf{PMIx Server version is newer than PMIx Client version}: +The implementation must negotiate capabilities during the initial handshake.\\ +This scenario is common if the (possibly containerized) PMIx client application is being run after a system software upgrade on the system. +Thus the PMIx Server in the \ac{RM} has been upgraded to a newer version of the \ac{PMIx} implementation and the client is still linked against the older version. +\end{enumerate} + +When the two \ac{PMIx}-enabled processes first connect to each other they need to first check the version of the library that they are each running. +This handshake often occurs during initialization (though it could occur on a per-operation basis depending on the \ac{PMIx} implementation), for example during the following operations: +\begin{itemize} +\item PMIx Clients: \refapi{PMIx_Init} +\item PMIx Tools: \refapi{PMIx_tool_init}, \refapi{PMIx_tool_attach_to_server} +\item PMIx Servers: \refapi{PMIx_server_init}, \refapi{pmix_server_client_connected2_fn_t}, \refapi{pmix_server_tool_connection_fn_t} +\end{itemize} + +Commonly this cross-version handshake occurs completely transparently to the consumers of the \ac{PMIx} interface since it happens inside the \ac{PMIx} implementation of these interfaces. +However, during the negotiation, some features available in one version might not be available in the other. +The consumer of the \ac{PMIx} interface should always be prepared to receive the \refconst{PMIX_ERR_NOT_SUPPORTED} error code from a \ac{PMIx} interface call that the other side either does not support or is not available in the version of the library with which they are linked. +After connecting to another \ac{PMIx} entity, the consumer of the \ac{PMIx} interface can use the \refapi{PMIx_Query_info} API to determine supported functionality and adapt accordingly. + +\littleheader{Related Interfaces} + +{\large \refapi{PMIx_Init}} +\pasteSignature{PMIx_Init} + +{\large \refapi{PMIx_tool_init}} +\pasteSignature{PMIx_tool_init} + +{\large \refapi{PMIx_tool_attach_to_server}} +\pasteSignature{PMIx_tool_attach_to_server} + +{\large \refapi{PMIx_server_init}} +\pasteSignature{PMIx_server_init} + +{\large \refapi{pmix_server_client_connected2_fn_t}} +\pasteSignature{pmix_server_client_connected2_fn_t} + +{\large \refapi{pmix_server_tool_connection_fn_t}} +\pasteSignature{pmix_server_tool_connection_fn_t} + +{\large \refapi{PMIx_Query_info}} +\pasteSignature{PMIx_Query_info} + +\littleheader{Related Constants} + +\refconst{PMIX_SUCCESS}\\ +\refconst{PMIX_ERR_NOT_SUPPORTED} + + %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%