Skip to content

Commit

Permalink
Wording fixes based on review
Browse files Browse the repository at this point in the history
Signed-off-by: Joshua Hursey <[email protected]>
  • Loading branch information
jjhursey committed Sep 28, 2021
1 parent 7085af6 commit d9b64e8
Showing 1 changed file with 10 additions and 10 deletions.
20 changes: 10 additions & 10 deletions App_Use_Cases.tex
Original file line number Diff line number Diff line change
Expand Up @@ -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.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
Expand Down Expand Up @@ -513,20 +513,20 @@ \subsection{Use Case Details}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Cross-Version Compatability}
\section{Cross-Version Compatibility}
\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.
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).

Expand All @@ -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.
Expand Down

0 comments on commit d9b64e8

Please sign in to comment.