Chap_API_Init.tex

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

The \ac{PMIx} library is required to be initialized and finalized around the usage of most \ac{PMIx} functions or macros.
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} Standard - those associated with the \ac{PMIx} \refterm{client} are defined in this chapter. Similar functions corresponding to the roles of \emph{server} and \emph{tool} are defined in Chapters \ref{chap:api_server} and \ref{chap:api_tools}, respectively.

Note that a process can only call \textit{one} of the initialization/finalization functional pairs from the set of three - 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 finalization function. Regardless of the role assumed by the process, all processes have access to the client \acp{API}. Thus, the \emph{server} and \emph{tool} roles can be considered supersets of the \ac{PMIx} client.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{\code{PMIx_Initialized}}
\declareapi{PMIx_Initialized}

%%%%
\summary

Determine if the \ac{PMIx} library has been initialized. This function may be used outside of the initialized and finalized region, and is usable by servers and tools in addition to clients.

%%%%
\format

\copySignature{PMIx_Initialized}{1.0}{
int PMIx_Initialized(void)
}

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}.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{\code{PMIx_Get_version}}
\declareapi{PMIx_Get_version}

%%%%
\summary

Get the \ac{PMIx} version information. This function may be used outside of the initialized and finalized region, and is usable by servers and tools in addition to clients.

%%%%
\format

\copySignature{PMIx_Get_version}{1.0}{
const char* PMIx_Get_version(void)
}

%%%%
\descr

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


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{\code{PMIx_Init}}
\declareapi{PMIx_Init}

%%%%
\summary

Initialize the \ac{PMIx} client library

%%%%
\format

\copySignature{PMIx_Init}{1.2}{
pmix_status_t \\
PMIx_Init(pmix_proc_t *proc, \\
\hspace*{10\sigspace}pmix_info_t info[], size_t ninfo)
}

\begin{arglist}
\arginout{proc}{proc structure (handle)}
\argin{info}{Array of \refstruct{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 \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{}
\pasteAttributeItem{PMIX_EXTERNAL_PROGRESS}
%
\declareAttribute{PMIX_EVENT_BASE}{"pmix.evbase"}{void*}{
Pointer to an \code{event_base} to use in place of the internal progress thread. All \ac{PMIx} library events are to be assigned to the provided event base. The event base \emph{must} be compatible with the event library used by the \ac{PMIx} implementation - e.g., either both the host and \ac{PMIx} library must use libevent, or both must use libev. Cross-matches are unlikely to work and should be avoided - it is the responsibility of the host to ensure that the \ac{PMIx} implementation supports (and was built with) the appropriate event library.
}

\vspace{\baselineskip}
If provided, the following attributes are used by the event notification system for inter-library coordination:

\pasteAttributeItem{PMIX_PROGRAMMING_MODEL}
\pasteAttributeItem{PMIX_MODEL_LIBRARY_NAME}
\pasteAttributeItem{PMIX_MODEL_LIBRARY_VERSION}
\pasteAttributeItem{PMIX_THREADING_MODEL}
\pasteAttributeItem{PMIX_MODEL_NUM_THREADS}
\pasteAttributeItem{PMIX_MODEL_NUM_CPUS}
\pasteAttributeItem{PMIX_MODEL_CPU_TYPE}
\pasteAttributeItem{PMIX_MODEL_AFFINITY_POLICY}

\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{Initialization events}

The following events are typically associated with calls to \refapi{PMIx_Init}:

\begin{constantdesc}
%
\declareconstitem{PMIX_MODEL_DECLARED}
Model declared.
%
\declareconstitem{PMIX_MODEL_RESOURCES}
Resource usage by a programming model has changed.
%
\declareconstitem{PMIX_OPENMP_PARALLEL_ENTERED}
An OpenMP parallel code region has been entered.
%
\declareconstitem{PMIX_OPENMP_PARALLEL_EXITED}
An OpenMP parallel code region has completed.
%
\end{constantdesc}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Initialization attributes}

The following attributes influence the behavior of \refapi{PMIx_Init}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Connection attributes}

These attributes are used to describe a TCP socket for rendezvous with the local \ac{RM} by passing them into the relevant initialization \ac{API} - thus, they are not typically accessed via the \refapi{PMIx_Get} \ac{API}.

%
\declareAttribute{PMIX_TCP_REPORT_URI}{"pmix.tcp.repuri"}{char*}{
If provided, directs that the TCP \ac{URI} be reported and indicates the desired method of reporting: \code{'-'} for stdout, \code{'+'} for stderr, or filename.
}
%
\declareAttribute{PMIX_TCP_URI}{"pmix.tcp.uri"}{char*}{
The \ac{URI} of the PMIx server to connect to, or a file name containing it in the form of \code{file:<name of file containing it>}.
}
%
\declareAttribute{PMIX_TCP_IF_INCLUDE}{"pmix.tcp.ifinclude"}{char*}{
Comma-delimited list of devices and/or \ac{CIDR} notation to include when establishing the TCP connection.
}
%
\declareAttribute{PMIX_TCP_IF_EXCLUDE}{"pmix.tcp.ifexclude"}{char*}{
Comma-delimited list of devices and/or \ac{CIDR} notation to exclude when establishing the TCP connection.
}
%
\declareAttribute{PMIX_TCP_IPV4_PORT}{"pmix.tcp.ipv4"}{int}{
The IPv4 port to be used..
}
%
\declareAttribute{PMIX_TCP_IPV6_PORT}{"pmix.tcp.ipv6"}{int}{
The IPv6 port to be used.
}
%
\declareAttribute{PMIX_TCP_DISABLE_IPV4}{"pmix.tcp.disipv4"}{bool}{
Set to \code{true} to disable IPv4 family of addresses.
}
%
\declareAttribute{PMIX_TCP_DISABLE_IPV6}{"pmix.tcp.disipv6"}{bool}{
Set to \code{true} to disable IPv6 family of addresses.
}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Programming model attributes}
\label{api:struct:attributes:model}

These attributes are associated with programming models.

%
\declareAttribute{PMIX_PROGRAMMING_MODEL}{"pmix.pgm.model"}{char*}{
Programming model being initialized (e.g., ``MPI'' or ``OpenMP'').
}
%
\declareAttribute{PMIX_MODEL_LIBRARY_NAME}{"pmix.mdl.name"}{char*}{
Programming model implementation ID (e.g., ``OpenMPI'' or ``MPICH'').
}
%
\declareAttribute{PMIX_MODEL_LIBRARY_VERSION}{"pmix.mld.vrs"}{char*}{
Programming model version string (e.g., ``2.1.1'').
}
%
\declareAttribute{PMIX_THREADING_MODEL}{"pmix.threads"}{char*}{
Threading model used (e.g., ``pthreads'').
}
%
\declareAttribute{PMIX_MODEL_NUM_THREADS}{"pmix.mdl.nthrds"}{uint64_t}{
Number of active threads being used by the model.
}
%
\declareAttribute{PMIX_MODEL_NUM_CPUS}{"pmix.mdl.ncpu"}{uint64_t}{
Number of cpus being used by the model.
}
%
\declareAttribute{PMIX_MODEL_CPU_TYPE}{"pmix.mdl.cputype"}{char*}{
Granularity - ``hwthread'', ``core'', etc.
}
%
\declareAttribute{PMIX_MODEL_PHASE_NAME}{"pmix.mdl.phase"}{char*}{
User-assigned name for a phase in the application execution (e.g., ``cfd reduction'').
}
%
\declareAttribute{PMIX_MODEL_PHASE_TYPE}{"pmix.mdl.ptype"}{char*}{
Type of phase being executed (e.g., ``matrix multiply'').
}
%
\declareAttribute{PMIX_MODEL_AFFINITY_POLICY}{"pmix.mdl.tap"}{char*}{
Thread affinity policy - e.g.:
         "master" (thread co-located with master thread),
         "close" (thread located on cpu close to master thread),
         "spread" (threads load-balanced across available cpus).
}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{\code{PMIx_Finalize}}
\declareapi{PMIx_Finalize}

%%%%
\summary

Finalize the PMIx client library.

%%%%
\format

\copySignature{PMIx_Finalize}{1.0}{
pmix_status_t \\
PMIx_Finalize(const pmix_info_t info[], size_t ninfo)
}

\begin{arglist}
\argin{info}{Array of \refstruct{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.

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

\pasteAttributeItem{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.

\subsection{Finalize attributes}

The following attribute influences the behavior of \refapi{PMIx_Finalize}.

%
\declareAttribute{PMIX_EMBED_BARRIER}{"pmix.embed.barrier"}{bool}{
Execute a blocking fence operation before executing the specified operation.
\refapi{PMIx_Finalize} does not include an internal barrier operation by default.
This attribute directs \refapi{PMIx_Finalize} to execute a barrier as part of the finalize operation.
}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{\code{PMIx_Progress}}
\declareapi{PMIx_Progress}

%%%%
\summary

Progress the \ac{PMIx} library.

%%%%
\format

\copySignature{PMIx_Progress}{4.0}{
void \\
PMIx_Progress(void)
}


%%%%
\descr

Progress the \ac{PMIx} library. Note that special care must be taken to avoid deadlocking in \ac{PMIx} callback functions and acp{API}.

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