From d9b64e8a66b7badb3a7eae38eb52b4e4c46732c2 Mon Sep 17 00:00:00 2001 From: Joshua Hursey Date: Wed, 11 Aug 2021 11:14:24 -0500 Subject: [PATCH] Wording fixes based on review Signed-off-by: Joshua Hursey --- App_Use_Cases.tex | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/App_Use_Cases.tex b/App_Use_Cases.tex index 50ee0514..7f16ec8f 100644 --- a/App_Use_Cases.tex +++ b/App_Use_Cases.tex @@ -6,7 +6,7 @@ \chapter{Use-Cases} The \ac{PMIx} standard provides many generic interfaces that can be composed into higher-level use cases in a variety of ways. While the specific interfaces and attributes are standardized, the use cases themselves are not (and should not) be standardized. Common use cases are included here as examples of how PMIx's generic interfaces \textit{might} be composed together for a higher-level purpose. The use cases are intended for both \ac{PMIx} interface users and library implementors. Whereby a better understanding of the general usage model within the community can help users picking up PMIx for the first and help implementors optimize their implementation for the common cases. -Each use case is structured to provide background information about the high-level use case as well as specific details about how the PMIx interfaces are used within the use case. Some use cases even provide code snippets. These code snippets are apart of larger code examples located within the standard's source code repository, and each complete code example is fully compilable and runnable. The related interfaces and attributes collected at the bottom of each use case are mainly for conveinence and link to the full standardized definitions. +Each use case is structured to provide background information about the high-level use case as well as specific details about how the PMIx interfaces are used within the use case. Some use cases even provide code snippets. These code snippets are apart of larger code examples located within the standard's source code repository, and each complete code example is fully compilable and runnable. The related interfaces and attributes collected at the bottom of each use case are mainly for convenience and link to the full standardized definitions. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -513,7 +513,7 @@ \subsection{Use Case Details} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\section{Cross-Version Compatability} +\section{Cross-Version Compatibility} \label{app:uc-cross-version} \subsection{Use Case Summary} @@ -521,12 +521,12 @@ \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. +As such, there is a need for \ac{PMIx} implementations 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. +The responsibility for providing cross-version compatibility is a feature of a specific \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 any given \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. +This use case is focused on cross-version compatibility between different 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). @@ -540,22 +540,22 @@ \subsection{Use Case Details} \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. +Thus the PMIx Server in the \ac{RM} is locked to an older version of that \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. +Thus the PMIx Server in the \ac{RM} has been upgraded to a newer version of that \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: +This handshake often occurs during initialization (though it could occur on a per-operation basis depending on the specific \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. +Commonly this cross-version handshake occurs completely transparently to the consumers of the \ac{PMIx} interface since it happens inside a specific \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.