Chap_API_Init.tex

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter: Initialization & Finalization
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Initialization and Finalization}
\label{chap:api_init}

The \ac{PMIx} library is required to be initialized and finalized around the usage of most of the \acp{API}.
The \acp{API} that may be used outside of the initialized and finalized region are noted.
All other \acp{API} must be used inside this region.

There are three sets of initialization and finalization functions depending upon the role of the process in the \ac{PMIx} universe.
Each of these functional sets are described in this chapter.
Note that a process can only call \textit{one} of the init/finalize functional pairs - e.g., a process that calls the client initialization function cannot also call the tool or server initialization functions, and must call the corresponding client finalize.

\adviceuserstart
Processes that initialize as a server or tool automatically are given access to all client \acp{API}.
Server initialization includes setting up the infrastructure to support local clients - thus, it necessarily includes overhead and an increased memory footprint.
Tool initialization automatically searches for a server to which it can connect --- if declared as a \textit{launcher}, the \ac{PMIx} library sets up the required ``hooks'' for other tools (e.g., debuggers) to attach to it.
\adviceuserend


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Query}
\label{chap:api_init:general}

The \ac{API} defined in this section can be used by any \ac{PMIx} process, regardless of their role in the \ac{PMIx} universe.

%%%%%%%%%%%
\subsection{\code{PMIx_Initialized}}
\declareapi{PMIx_Initialized}

%%%%
\format

\versionMarker{1.0}
\cspecificstart
\begin{codepar}
int PMIx_Initialized(void)
\end{codepar}
\cspecificend

A value of \code{1} (true) will be returned if the \ac{PMIx} library has been initialized, and \code{0} (false) otherwise.

\rationalestart
The return value is an integer for historical reasons as that was the signature of prior PMI libraries.
\rationaleend

%%%%
\descr

Check to see if the \ac{PMIx} library has been initialized using any of the init functions:
\refapi{PMIx_Init}, \refapi{PMIx_server_init}, or \refapi{PMIx_tool_init}.

%%%%%%%%%%%
\subsection{\code{PMIx_Get_version}}
\declareapi{PMIx_Get_version}

%%%%
\summary

Get the \ac{PMIx} version information.

%%%%
\format

\versionMarker{1.0}
\cspecificstart
\begin{codepar}
const char* PMIx_Get_version(void)
\end{codepar}
\cspecificend

%%%%
\descr

Get the \ac{PMIx} version string.
Note that the provided string is statically defined and must \textit{not} be free'd.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Client Initialization and Finalization}
\label{chap:api_init:client}

Initialization and finalization routines for \ac{PMIx} clients.

\adviceuserstart
The \ac{PMIx} \textit{ad hoc} v1.0 Standard defined the \refapi{PMIx_Init} function, but modified the function signature in the v1.2 version. The \textit{ad hoc} v1.0 version is not included in this document to avoid confusion.
\adviceuserend


%%%%%%%%%%%
\subsection{\code{PMIx_Init}}
\declareapi{PMIx_Init}

%%%%
\summary

Initialize the \ac{PMIx} client library

%%%%
\format

\versionMarker{1.2}
\cspecificstart
\begin{codepar}
pmix_status_t
PMIx_Init(pmix_proc_t *proc,
          pmix_info_t info[], size_t ninfo)
\end{codepar}
\cspecificend

\begin{arglist}
\arginout{proc}{proc structure (handle)}
\argin{info}{Array of \refattr{pmix_info_t} structures (array of handles)}
\argin{ninfo}{Number of element in the \refarg{info} array (\code{size_t})}
\end{arglist}

Returns \refconst{PMIX_SUCCESS} or a negative value corresponding to a \ac{PMIx} error constant.

\optattrstart
The following attributes are optional for implementers of \ac{PMIx} libraries:

\pasteAttributeItemBegin{PMIX_USOCK_DISABLE} If the library supports Unix socket connections, this attribute may be supported for disabling it.
\pasteAttributeItemEnd{}
\pasteAttributeItemBegin{PMIX_SOCKET_MODE} If the library supports socket connections, this attribute may be supported for setting the socket mode.
\pasteAttributeItemEnd{}
\pasteAttributeItemBegin{PMIX_SINGLE_LISTENER} If the library supports multiple methods for clients to connect to servers, this attribute may be supported for disabling all but one of them.
\pasteAttributeItemEnd{}
\pasteAttributeItemBegin{PMIX_TCP_REPORT_URI} If the library supports TCP socket connections, this attribute may be supported for reporting the URI.
\pasteAttributeItemEnd{}
\pasteAttributeItemBegin{PMIX_TCP_IF_INCLUDE} If the library supports TCP socket connections, this attribute may be supported for specifying the interfaces to be used.
\pasteAttributeItemEnd{}
\pasteAttributeItemBegin{PMIX_TCP_IF_EXCLUDE} If the library supports TCP socket connections, this attribute may be supported for specifying the interfaces that are \textit{not} to be used.
\pasteAttributeItemEnd{}
\pasteAttributeItemBegin{PMIX_TCP_IPV4_PORT} If the library supports IPV4 connections, this attribute may be supported for specifying the port to be used.
\pasteAttributeItemEnd{}
\pasteAttributeItemBegin{PMIX_TCP_IPV6_PORT} If the library supports IPV6 connections, this attribute may be supported for specifying the port to be used.
\pasteAttributeItemEnd{}
\pasteAttributeItemBegin{PMIX_TCP_DISABLE_IPV4} If the library supports IPV4 connections, this attribute may be supported for disabling it.
\pasteAttributeItemEnd{}
\pasteAttributeItemBegin{PMIX_TCP_DISABLE_IPV6} If the library supports IPV6 connections, this attribute may be supported for disabling it.
\pasteAttributeItemEnd{}
\pastePRIAttributeItem{PMIX_EVENT_BASE}
\pastePRIAttributeItemBegin{PMIX_GDS_MODULE} This attribute is specific to the \ac{PRI} and controls only the selection of \ac{GDS} module for internal use by the process. Module selection for interacting with the server is performed dynamically during the connection process.
\pastePRIAttributeItemEnd{}
\optattrend

%%%%
\descr

Initialize the \ac{PMIx} client, returning the process identifier assigned to this client's application in the provided \refstruct{pmix_proc_t} struct.
Passing a value of \code{NULL} for this parameter is allowed if the user wishes solely to initialize the \ac{PMIx} system and does not require return of the identifier at that time.

When called, the \ac{PMIx} client shall check for the required connection information of the local \ac{PMIx} server and establish the connection.
If the information is not found, or the server connection fails, then an appropriate error constant shall be returned.

If successful, the function shall return \refconst{PMIX_SUCCESS} and fill the \refarg{proc} structure (if provided) with the server-assigned namespace and rank of the process within the application.
In addition, all startup information provided by the resource manager shall be made available to the client process via subsequent calls to \refapi{PMIx_Get}.

The \ac{PMIx} client library shall be reference counted, and so multiple calls to \refapi{PMIx_Init} are allowed by the standard.
Thus, one way for an application process to obtain its namespace and rank is to simply call \refapi{PMIx_Init} with a non-NULL \refarg{proc} parameter.
Note that each call to \refapi{PMIx_Init} must be balanced with a call to \refapi{PMIx_Finalize} to maintain the reference count.

Each call to \refapi{PMIx_Init} may contain an array of \refstruct{pmix_info_t} structures passing directives to the \ac{PMIx} client library as per the above attributes.

Multiple calls to \refapi{PMIx_Init} shall not include conflicting directives.
The \refapi{PMIx_Init} function will return an error when directives that conflict with prior directives are encountered.


%%%%%%%%%%%
\subsection{\code{PMIx_Finalize}}
\declareapi{PMIx_Finalize}

%%%%
\summary

Finalize the PMIx client library.

%%%%
\format

\versionMarker{1.0}
\cspecificstart
\begin{codepar}
pmix_status_t
PMIx_Finalize(const pmix_info_t info[], size_t ninfo)
\end{codepar}
\cspecificend

\begin{arglist}
\argin{info}{Array of \refattr{pmix_info_t} structures (array of handles)}
\argin{ninfo}{Number of element in the \refarg{info} array (\code{size_t})}
\end{arglist}

Returns \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant.

\optattrstart
The following attributes are optional for implementers of \ac{PMIx} libraries:

\pastePRIAttributeItem{PMIX_EMBED_BARRIER}
\optattrend

%%%%
\descr

Decrement the \ac{PMIx} client library reference count.
When the reference count reaches zero, the library will finalize the \ac{PMIx} client, closing the connection with the local \ac{PMIx} server and releasing all internally allocated memory.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Tool Initialization and Finalization}
\label{chap:api_init:tool}

Initialization and finalization routines for \ac{PMIx} tools.

%%%%%%%%%%%
\subsection{\code{PMIx_tool_init}}
\declareapi{PMIx_tool_init}

%%%%
\summary

Initialize the \ac{PMIx} library for operating as a tool.

%%%%
\format

\versionMarker{2.0}
\cspecificstart
\begin{codepar}
pmix_status_t
PMIx_tool_init(pmix_proc_t *proc,
               pmix_info_t info[], size_t ninfo)
\end{codepar}
\cspecificend

\begin{arglist}
\arginout{proc}{\refstruct{pmix_proc_t} structure (handle)}
\argin{info}{Array of \refattr{pmix_info_t} structures (array of handles)}
\argin{ninfo}{Number of element in the \refarg{info} array (\code{size_t})}
\end{arglist}

Returns \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant.

\reqattrstart
The following attributes are required to be supported by all \ac{PMIx} libraries:

\pastePRIAttributeItem{PMIX_TOOL_NSPACE}
\pastePRIAttributeItem{PMIX_TOOL_RANK}
\pastePRIAttributeItem{PMIX_TOOL_DO_NOT_CONNECT}
\pastePRIAttributeItem{PMIX_SERVER_URI}

\reqattrend

\optattrstart
The following attributes are optional for implementers of \ac{PMIx} libraries:

\pastePRIAttributeItem{PMIX_CONNECT_TO_SYSTEM}
\pastePRIAttributeItem{PMIX_CONNECT_SYSTEM_FIRST}
\pastePRIAttributeItem{PMIX_SERVER_PIDINFO}
\pastePRIAttributeItem{PMIX_TCP_URI}
\pastePRIAttributeItem{PMIX_CONNECT_RETRY_DELAY}
\pastePRIAttributeItem{PMIX_CONNECT_MAX_RETRIES}
\pasteAttributeItemBegin{PMIX_SOCKET_MODE} If the library supports socket connections, this attribute may be supported for setting the socket mode.
\pasteAttributeItemEnd{}
\pastePRIAttributeItemBegin{PMIX_TCP_REPORT_URI} If the library supports TCP socket connections, this attribute may be supported for reporting the URI.
\pastePRIAttributeItemEnd{}
\pastePRIAttributeItemBegin{PMIX_TCP_IF_INCLUDE} If the library supports TCP socket connections, this attribute may be supported for specifying the interfaces to be used.
\pastePRIAttributeItemEnd{}
\pastePRIAttributeItemBegin{PMIX_TCP_IF_EXCLUDE} If the library supports TCP socket connections, this attribute may be supported for specifying the interfaces that are \textit{not} to be used.
\pastePRIAttributeItemEnd{}
\pastePRIAttributeItemBegin{PMIX_TCP_IPV4_PORT} If the library supports IPV4 connections, this attribute may be supported for specifying the port to be used.
\pastePRIAttributeItemEnd{}
\pastePRIAttributeItemBegin{PMIX_TCP_IPV6_PORT} If the library supports IPV6 connections, this attribute may be supported for specifying the port to be used.
\pastePRIAttributeItemEnd{}
\pastePRIAttributeItemBegin{PMIX_TCP_DISABLE_IPV4} If the library supports IPV4 connections, this attribute may be supported for disabling it.
\pastePRIAttributeItemEnd{}
\pastePRIAttributeItemBegin{PMIX_TCP_DISABLE_IPV6} If the library supports IPV6 connections, this attribute may be supported for disabling it.
\pastePRIAttributeItemEnd{}
\pastePRIAttributeItem{PMIX_EVENT_BASE}
\pastePRIAttributeItemBegin{PMIX_GDS_MODULE} This attribute is specific to the \ac{PRI} and controls only the selection of \ac{GDS} module for internal use by the process. Module selection for interacting with the server is performed dynamically during the connection process.
\pastePRIAttributeItemEnd{}

\optattrend

%%%%
\descr

Initialize the \ac{PMIx} tool, returning the process identifier assigned to this tool in the provided \refstruct{pmix_proc_t} struct. The \refarg{info} array is used to pass user requests pertaining to the init and subsequent operations. Passing a \code{NULL} value for the array pointer is supported if no directives are desired.

If called with the \refattr{PMIX_TOOL_DO_NOT_CONNECT} attribute, the \ac{PMIx} tool library will fully initialize but not attempt to connect to a \ac{PMIx} server. The tool can connect to a server at a later point in time, if desired. In all other cases, the \ac{PMIx} tool library will attempt to connect to according to the following precedence chain:

\begin{itemize}
    \item if \refattr{PMIX_SERVER_URI} or \refattr{PMIX_TCP_URI} is given, then connection will be attempted to the server at the specified \ac{URI}. Note that it is an error for both of these attributes to be specified. \refattr{PMIX_SERVER_URI} is the preferred method as it is more generalized --- \refattr{PMIX_TCP_URI} is provided for those cases where the user specifically wants to use a TCP transport for the connection and wants to error out if it isn't available or cannot succeed. The \ac{PMIx} library will return an error if connection fails --- it will not proceed to check for other connection options as the user specified a particular one to use
    \item if \refattr{PMIX_SERVER_PIDINFO} was provided, then the tool will search under the directory provided by the PMIX\_SERVER\_TMPDIR environmental variable for a rendezvous file created by the process corresponding to that \ac{PID}. The \ac{PMIx} library will return an error if the rendezvous file cannot be found, or the connection is refused by the server
    \item if \refattr{PMIX_CONNECT_TO_SYSTEM} is given, then the tool will search for a system-level rendezvous file created by a \ac{PMIx} server in the directory specified by the PMIX\_SYSTEM\_TMPDIR environmental variable. If found, then the tool will attempt to connect to it. An error is returned if the rendezvous file cannot be found or the connection is refused.
    \item if \refattr{PMIX_CONNECT_SYSTEM_FIRST} is given, then the tool will search for a system-level rendezvous file created by a \ac{PMIx} server in the directory specified by the PMIX\_SYSTEM\_TMPDIR environmental variable. If found, then the tool will attempt to connect to it. In this case, no error will be returned if the rendezvous file is not found or connection is refused --- the \ac{PMIx} library will silently continue to the next option
    \item by default, the tool will search the directory tree under the directory provided by the PMIX\_SERVER\_TMPDIR environmental variable for rendezvous files of \ac{PMIx} servers, attempting to connect to each it finds until one accepts the connection. If no rendezvous files are found, or all contacted servers refuse connection, then the \ac{PMIx} library will return an error.
\end{itemize}

If successful, the function will return \refconst{PMIX_SUCCESS} and will fill the provided structure (if provided) with the server-assigned namespace and rank of the tool. Note that each connection attempt in the above precedence chain will retry (with delay between each retry) a number of times according to the values of the corresponding attributes. Default is no retries.

Note that the \ac{PMIx} tool library is referenced counted, and so multiple calls to \refapi{PMIx_tool_init} are allowed.
Thus, one way to obtain the namespace and rank of the process is to simply call \refapi{PMIx_tool_init} with a non-NULL parameter.


%%%%%%%%%%%
\subsection{\code{PMIx_tool_finalize}}
\declareapi{PMIx_tool_finalize}

%%%%
\summary

Finalize the \ac{PMIx} library for a tool connection.

%%%%
\format

\versionMarker{2.0}
\cspecificstart
\begin{codepar}
pmix_status_t
PMIx_tool_finalize(void)
\end{codepar}
\cspecificend

Returns \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant.

%%%%
\descr

Finalize the PMIx tool library, closing the connection to the server.
An error code will be returned if, for some reason, the connection cannot be cleanly terminated --- in this case, the connection is dropped.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Server Initialization and Finalization}
\label{chap:api_init:server}

Initialization and finalization routines for \ac{PMIx} servers.

%%%%%%%%%%%
\subsection{\code{PMIx_server_init}}
\declareapi{PMIx_server_init}

%%%%
\summary

Initialize the \ac{PMIx} server.

%%%%
\format

\versionMarker{1.0}
\cspecificstart
\begin{codepar}
pmix_status_t
PMIx_server_init(pmix_server_module_t *module,
                 pmix_info_t info[], size_t ninfo)
\end{codepar}
\cspecificend

\begin{arglist}
\arginout{module}{\refstruct{pmix_server_module_t} structure (handle)}
\argin{info}{Array of \refattr{pmix_info_t} structures (array of handles)}
\argin{ninfo}{Number of elements in the \refarg{info} array (\code{size_t})}
\end{arglist}

Returns \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant.

\reqattrstart
The following attributes are required to be supported by all \ac{PMIx} libraries:

\pastePRIAttributeItem{PMIX_SERVER_NSPACE}
\pastePRIAttributeItem{PMIX_SERVER_RANK}
\pastePRIAttributeItem{PMIX_SERVER_TMPDIR}
\pastePRIAttributeItem{PMIX_SYSTEM_TMPDIR}
\pastePRIAttributeItem{PMIX_SERVER_TOOL_SUPPORT}
\pastePRIAttributeItem{PMIX_SERVER_SYSTEM_SUPPORT}

\reqattrend


\optattrstart
The following attributes are optional for implementers of \ac{PMIx} libraries:

\pastePRIAttributeItemBegin{PMIX_USOCK_DISABLE} If the library supports Unix socket connections, this attribute may be supported for disabling it.
\pastePRIAttributeItemEnd{}
\pasteAttributeItemBegin{PMIX_SOCKET_MODE} If the library supports socket connections, this attribute may be supported for setting the socket mode.
\pasteAttributeItemEnd{}
\pastePRIAttributeItemBegin{PMIX_TCP_REPORT_URI} If the library supports TCP socket connections, this attribute may be supported for reporting the URI.
\pastePRIAttributeItemEnd{}
\pastePRIAttributeItemBegin{PMIX_TCP_IF_INCLUDE} If the library supports TCP socket connections, this attribute may be supported for specifying the interfaces to be used.
\pastePRIAttributeItemEnd{}
\pastePRIAttributeItemBegin{PMIX_TCP_IF_EXCLUDE} If the library supports TCP socket connections, this attribute may be supported for specifying the interfaces that are \textit{not} to be used.
\pastePRIAttributeItemEnd{}
\pastePRIAttributeItemBegin{PMIX_TCP_IPV4_PORT} If the library supports IPV4 connections, this attribute may be supported for specifying the port to be used.
\pastePRIAttributeItemEnd{}
\pastePRIAttributeItemBegin{PMIX_TCP_IPV6_PORT} If the library supports IPV6 connections, this attribute may be supported for specifying the port to be used.
\pastePRIAttributeItemEnd{}
\pastePRIAttributeItemBegin{PMIX_TCP_DISABLE_IPV4} If the library supports IPV4 connections, this attribute may be supported for disabling it.
\pastePRIAttributeItemEnd{}
\pastePRIAttributeItemBegin{PMIX_TCP_DISABLE_IPV6} If the library supports IPV6 connections, this attribute may be supported for disabling it.
\pastePRIAttributeItemEnd{}
\pastePRIAttributeItemBegin{PMIX_SERVER_REMOTE_CONNECTIONS} If the library supports connections from remote tools, this attribute may be supported for enabling or disabling it.
\pastePRIAttributeItemEnd{}

\pastePRIAttributeItem{PMIX_EVENT_BASE}
\pastePRIAttributeItemBegin{PMIX_GDS_MODULE} This attribute is specific to the \ac{PRI} and controls only the selection of \ac{GDS} module for internal use by the process. Module selection for interacting with the server is performed dynamically during the connection process.
\pastePRIAttributeItemEnd{}

\optattrend

%%%%
\descr

Initialize the \ac{PMIx} server support library, and provide a pointer to a \refapi{pmix_server_module_t} structure containing the caller's callback functions.
The array of \refstruct{pmix_info_t} structs is used to pass additional info that may be required by the server when initializing.
For example, it may include the \refconst{PMIX_SERVER_TOOL_SUPPORT} key, thereby indicating that the daemon is willing to accept connection requests from tools.

\advicermstart
Providing a value of \code{NULL} for the \refarg{module} argument is permitted, as is passing an empty \refarg{module} structure. Doing so indicates that the host environment will not provide support for multi-node operations such as \refapi{PMIx_Fence}, but does intend to support local clients access to information.
\advicermend

%%%%%%%%%%%
\subsection{\code{PMIx_server_finalize}}
\declareapi{PMIx_server_finalize}

%%%%
\summary

Finalize the PMIx server library.

%%%%
\format

\versionMarker{1.0}
\cspecificstart
\begin{codepar}
pmix_status_t
PMIx_server_finalize(void)
\end{codepar}
\cspecificend

Returns \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant.

%%%%
\descr

Finalize the \ac{PMIx} server support library, terminating all connections to attached tools and any local clients.
All memory usage is released.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%