App_Python.tex

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Appendix: Python bindings
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Python Bindings}
\label{app:python}

While the \ac{PMIx} Standard is defined in terms of C-based \acp{API}, there is no intent to limit the use of \ac{PMIx} to that specific language. Support for other languages is captured in the Standard by describing their equivalent syntax for the \ac{PMIx} \acp{API} and native forms for the \ac{PMIx} datatypes. This Appendix specifically deals with Python interfaces, beginning with a review of the \ac{PMIx} datatypes. Support is restricted to Python 3 and above - i.e., the Python bindings do not support Python 2.

Note: the \ac{PMIx} \acp{API} have been loosely collected into three Python classes based on their \ac{PMIx} “class” (i.e., client, server, and tool). All processes have access to a basic set of the \acp{API}, and therefore those have been included in the “client” class. Servers can utilize any of those functions plus a set focused on operations not commonly executed by an application process. Finally, tools can also act as servers but have their own initialization function.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Design Considerations}
\label{app:python:design}

Several issues arose during design of the Python bindings:

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Error Codes vs Python Exceptions}
\label{app:python:exceptions}

The C programming language reports errors through the return of the corresponding integer status codes. \ac{PMIx} has defined a range of negative values for this purpose. However, Python has the option of raising \emph{exceptions} that effectively operate as interrupts that can be trapped if the program appropriately tests for them. The \ac{PMIx} Python bindings opted to follow the C-based standard and return \ac{PMIx} status codes in lieu of raising exceptions as this method was considered more consistent for those working in both domains.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Representation of Structured Data}
\label{app:python:rep}

\ac{PMIx} utilizes a number of C-language structures to efficiently bundle related information. For example, the \ac{PMIx} process identifier is represented as a struct containing a character array for the namespace and a 32-bit unsigned integer for the process rank. There are several options for translating such objects to Python – e.g., the \ac{PMIx} process identifier could be represented as a two-element tuple (nspace, rank) or as a dictionary {‘nspace’: name, ‘rank’: 0}. Exploration found no discernible benefit to either representation, nor was any clearly identifiable rationale developed that would lead a user to expect one versus the other for a given \ac{PMIx} data type. Consistency in the translation (i.e., exclusively using tuple or dictionary) appeared to be the most important criterion. Hence, the decision was made to express all complex datatypes as Python dictionaries.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Datatype Definitions}
\label{app:python:types}

\ac{PMIx} defines a number of datatypes comprised of fixed-size character arrays, restricted range integers (e.g., uint32_t), and structures. Each datatype is represented by a named unsigned 16-bit integer (\code{uint16_t}) constant. Users are advised to use the named \ac{PMIx} constants for indicating datatypes instead of integer values to ensure compatibility with future PMIx versions.

With only a few exceptions, the C-based \ac{PMIx} datatypes defined in \chapterref{chap:struct} directly translate to Python. However, Python lacks the size-specific value definitions of C (e.g., \code{uint8_t}) and thus some care must be taken to protect against overflow/underflow situations when moving between the languages. Python bindings that accept values including \ac{PMIx} datatypes shall therefore have the datatype and associated value checked for compatibility with their \ac{PMIx}-defined equivalents, returning an error if:

\begin{itemize}
    \item datatypes not defined by \ac{PMIx} are encountered
    \item provided values fall outside the range of the C-equivalent definition - e.g., if a value identified as \refconst{PMIX_UINT8} lies outside the \code{uint8_t}range
\end{itemize}

Note that explicit labeling of \ac{PMIx} data type, even when Python itself doesn’t care, is often required for the Python bindings to know how to properly interpret and label the provided value when passing it to the \ac{PMIx} library.

Table~\ref{app:python:ctopy} lists the correspondence between data types in the two languages.

\begin{landscape}
\begin{small}
    \begin{longtable}{ | p{4.5cm} | p{4cm} | p{3cm} | p{5.5cm} |}
        \caption{C-to-Python Datatype Correspondence} \label{app:python:ctopy} \\
        \hline
        C-Definition & PMIx Name & Python Definition & Notes \\ \hline
        \endhead
        \code{bool} & \refconst{PMIX_BOOL} & boolean & \\ \hline
        \code{byte} & \refconst{PMIX_BYTE} & A single element byte array (i.e., a byte array of length one) & \\ \hline
        \code{char*} & \refconst{PMIX_STRING} & string & \\ \hline
        \code{size_t} & \refconst{PMIX_SIZE} & integer & \\ \hline
        \code{pid_t} & \refconst{PMIX_PID} & integer & value shall be limited to the \code{uint32_t} range \\ \hline
        \code{int, int8_t, int16_t, int32_t, int64_t} & \refconst{PMIX_INT}, \refconst{PMIX_INT8}, \refconst{PMIX_INT16}, \refconst{PMIX_INT32}, \refconst{PMIX_INT64} & integer & value shall be limited to its corresponding range \\ \hline
        \code{uint, uint8_t, uint16_t, uint32_t, uint64_t} & \refconst{PMIX_UINT}, \refconst{PMIX_UINT8}, \refconst{PMIX_UINT16}, \refconst{PMIX_UINT32}, \refconst{PMIX_UINT64} & integer & value shall be limited to its corresponding range \\ \hline
        \code{float, double} & \refconst{PMIX_FLOAT}, \refconst{PMIX_DOUBLE} & float & value shall be limited to its corresponding range \\ \hline
        \code{struct timeval} & \refconst{PMIX_TIMEVAL} & \{'sec': sec, 'usec': microsec\} & each field is an integer value \\ \hline
        \code{time_t} & \refconst{PMIX_TIME} & integer & limited to positive values \\ \hline
        \refstruct{pmix_data_type_t} & \refconst{PMIX_DATA_TYPE} & integer & value shall be limited to the \code{uint16_t} range \\ \hline
        \refstruct{pmix_status_t} & \refconst{PMIX_STATUS} & integer & \\ \hline
        \refstruct{pmix_key_t} & N/A & \pylabel{key}string & The string's length shall be limited to one less than the size of the \refstruct{pmix_key_t} array (to reserve space for the terminating \code{NULL})  \\ \hline
        \refstruct{pmix_nspace_t} & N/A & \pylabel{nspace}string & The string's length shall be limited to one less than the size of the \refstruct{pmix_nspace_t} array (to reserve space for the terminating \code{NULL})  \\ \hline
        \refstruct{pmix_rank_t} & \refconst{PMIX_PROC_RANK} & \pylabel{rank}integer & value shall be limited to the \code{uint32_t} range excepting the reserved values near \code{UINT32_MAX} \\ \hline
        \refstruct{pmix_proc_t} & \refconst{PMIX_PROC} & \pylabel{proc}\{'nspace': nspace, 'rank': rank\} & \refarg{nspace} is a Python string and \refarg{rank} is an integer value. The \refarg{nspace} string's length shall be limited to one less than the size of the \refstruct{pmix_nspace_t} array (to reserve space for the terminating \code{NULL}), and the \refarg{rank} value shall conform to the constraints associated with \refstruct{pmix_rank_t} \\ \hline
        \refstruct{pmix_byte_object_t} & \refconst{PMIX_BYTE_OBJECT} & \pylabel{byteobject}\{'bytes': bytes, 'size': size\} & \refarg{bytes} is a Python byte array and \refarg{size} is the integer number of bytes in that array. \\ \hline
        \refstruct{pmix_persistence_t} & \refattr{PMIX_PERSISTENCE} & integer & value shall be limited to the \code{uint8_t} range \\ \hline
        \refstruct{pmix_scope_t} & \refconst{PMIX_SCOPE} & integer & value shall be limited to the \code{uint8_t} range \\ \hline
        \refstruct{pmix_data_range_t} & \refattr{PMIX_RANGE} & \pylabel{range}integer & value shall be limited to the \code{uint8_t} range \\ \hline
        \refstruct{pmix_proc_state_t} & \refconst{PMIX_PROC_STATE} & integer & value shall be limited to the \code{uint8_t} range \\ \hline
        \refstruct{pmix_proc_info_t} & \refconst{PMIX_PROC_INFO} & \{'proc': \{'nspace': nspace, 'rank': rank\}, 'hostname': hostname, 'executable': executable, 'pid': pid, 'exitcode': exitcode, 'state': state\} & \refarg{proc} is a Python \refpy{proc} dictionary; \refarg{hostname} and \refarg{executable} are Python strings; and \refarg{pid}, \refarg{exitcode}, and \refarg{state} are Python integers \\ \hline
        \refstruct{pmix_data_array_t} & \refconst{PMIX_DATA_ARRAY} & \pylabel{array}\{'type': type, 'array': array\} & \refarg{type} is the \ac{PMIx} type of object in the array and \refarg{array} is a Python \emph{list} containing the individual array elements. Note that \refarg{array} can consist of \emph{any} \ac{PMIx} types, including (for example) a Python \refpy{info} object that itself contains an \refpy{array} value \\ \hline
        \refstruct{pmix_info_directives_t}  & \refconst{PMIX_INFO_DIRECTIVES} & \pylabel{info directives}list & list of integer values (defined in Section \ref{api:struct:infodirs}) \\ \hline
        \refstruct{pmix_alloc_directive_t} & \refconst{PMIX_ALLOC_DIRECTIVE} & \pylabel{allocdir}integer & value shall be limited to the \code{uint8_t} range \\ \hline
        \refstruct{pmix_iof_channel_t} & \refconst{PMIX_IOF_CHANNEL} & \pylabel{channel}list & list of integer values (defined in Section \ref{api:tool:iofchannels}) \\ \hline
        \refstruct{pmix_envar_t} & \refconst{PMIX_ENVAR} & \{'envar': envar, 'value': value, 'separator': separator\} & \refarg{envar} and \refarg{value} are Python strings, and \refarg{separator} a single-character Python string \\ \hline
        \refstruct{pmix_value_t} & \refconst{PMIX_VALUE} & \pylabel{value}\{'value': value, 'val_type': type\} & \refarg{type} is the \ac{PMIx} datatype of \refarg{value}, and \refarg{value} is the associated value expressed in the appropriate Python form for the specified datatype  \\ \hline
        \refstruct{pmix_info_t} & \refconst{PMIX_INFO} & \pylabel{info}\{'key': key, 'flags': flags, value': value, 'val_type': type\} & \refarg{key} is a Python string \refpy{key}, \refarg{flags} is an \refpy{info directives} value, \refarg{type} is the \ac{PMIx} datatype of \refarg{value}, and \refarg{value} is the associated value expressed in the appropriate Python form for the specified datatype \\ \hline
        \refstruct{pmix_pdata_t} & \refconst{PMIX_PDATA} & \pylabel{pdata}\{'proc': \{'nspace': nspace, 'rank': rank\}, 'key': key, 'value': value, 'val_type': type\} & \refarg{proc} is a Python \refpy{proc} dictionary; \refarg{key} is a Python string \refpy{key}; \refarg{type} is the \ac{PMIx} datatype of \refarg{value}; and \refarg{value} is the associated value expressed in the appropriate Python form for the specified datatype  \\ \hline
        \refstruct{pmix_app_t} & \refconst{PMIX_APP} & \pylabel{app}\{'cmd': cmd, 'argv': [argv], 'env': [env], 'maxprocs': maxprocs, 'info': [info]\} & \refarg{cmd} is a Python string; \refarg{argv} and \refarg{env} are Python \emph{lists} containing Python strings; \refarg{maxprocs} is an integer; and \refarg{info} is a Python \emph{list} of \refpy{info} values   \\ \hline
        \refstruct{pmix_query_t} & \refconst{PMIX_QUERY} & \pylabel{query}\{'keys': [keys], 'qualifiers': [info]\} & \refarg{keys} is a Python \emph{list} of Python strings, and \refarg{qualifiers} is a Python \emph{list} of \refpy{info} values \\ \hline
        \refstruct{pmix_regattr_t} & \refconst{PMIX_REGATTR} & \pylabel{regattr}\{'name': name, 'key': key, 'type': type, 'info': [info], 'description': [desc]\} & \refarg{name} and \refarg{string} are Python strings; \refarg{type} is the \ac{PMIx} datatype for the attribute's value; \refarg{info} is a Python \emph{list} of \refpy{info} values; and \refarg{description} is a list of Python strings describing the attribute  \\ \hline
        \refstruct{pmix_job_state_t} & \refconst{PMIX_JOB_STATE} & integer & value shall be limited to the \code{uint8_t} range \\ \hline
        \refstruct{pmix_link_state_t} & \refconst{PMIX_LINK_STATE} & integer & value shall be limited to the \code{uint8_t} range \\ \hline
        \refstruct{pmix_cpuset_t} & \refconst{PMIX_PROC_CPUSET} & \pylabel{cpuset}\{'source': source, 'cpus': bitmap\} & \refarg{source} is a string name of the library that created the cpuset; and \refarg{cpus} is a list of string ranges identifying the \acp{PU} to which the process is bound (e.g., [1, 3-5, 7]) \\ \hline
        \refstruct{pmix_locality_t} & \refconst{PMIX_LOCTYPE} & \pylabel{locality}list & list of integer values (defined in Section \ref{api:proc:locality}) describing the relative locality of the specified local process \\ \hline
        \refstruct{pmix_fabric_t} & N/A & \pylabel{fabric}\{'name': name, 'index': idx, 'info': [info]\} & \refarg{name} is the string name assigned to the fabric; \refarg{index} is the integer ID assigned to the fabric; \refarg{info} is a list of \refpy{info} describing the fabric \\ \hline
        \refstruct{pmix_endpoint_t} & \refconst{PMIX_ENDPOINT} & \pylabel{endpoint}\{'uuid': uuid, 'osname': osname, endpt': endpt\} & \refarg{uuid} is the string system-unique identifier assigned to the device; \refarg{osname} is the operating system name assigned to the device; \refarg{endpt} is a \refpy{byteobject} containing the endpoint information \\ \hline
        \refstruct{pmix_device_distance_t} & \refconst{PMIX_DEVICE_DIST} & \pylabel{devdist}\{'uuid': uuid, 'osname': osname, mindist': mindist, 'maxdist': maxdist\} & \refarg{uuid} is the string system-unique identifier assigned to the device; \refarg{osname} is the operating system name assigned to the device; and \refarg{mindist} and \refarg{maxdist} are Python integers \\ \hline
        \refstruct{pmix_coord_t} & \refconst{PMIX_COORD} & \pylabel{coord}\{'view': view, 'coord': [coords]\} & \refarg{view} is the \refstruct{pmix_coord_view_t} of the coordinate; and \refarg{coord} is a list of integer coordinates, one for each dimension of the fabric \\ \hline
        \refstruct{pmix_geometry_t} & \refconst{PMIX_GEOMETRY} & \pylabel{geometry}\{'fabric': idx, 'uuid': uuid, 'osname': osname, coordinates': [coords]\} & \refarg{fabric} is the Python integer index of the fabric; \refarg{uuid} is the string system-unique identifier assigned to the device; \refarg{osname} is the operating system name assigned to the device; and \refarg{coordinates} is a list of \refpy{coord} containing the coordinates for the device across all views \\ \hline
        \refstruct{pmix_device_type_t} & \refconst{PMIX_DEVTYPE} & \pylabel{devtype}list & list of integer values (defined in Section \ref{api:proc:devtype}) \\ \hline
        \refstruct{pmix_bind_envelope_t} & N/A & \pylabel{bindenv}integer & one of the values defined in Section \ref{api:proc:bindenv} \\ \hline
    \end{longtable}
\end{small}
\end{landscape}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Example}
Converting a C-based program to its Python equivalent requires translation of the relevant datatypes as well as use of the appropriate \ac{API} form. An example small program may help illustrate the changes. Consider the following C-based program snippet:

\cspecificstart
\begin{codepar}

#include <pmix.h>
...

pmix_info_t info[2];

PMIX_INFO_LOAD(&info[0], PMIX_PROGRAMMING_MODEL, "TEST", PMIX_STRING)
PMIX_INFO_LOAD(&info[1], PMIX_MODEL_LIBRARY_NAME, "PMIX", PMIX_STRING)

rc = PMIx_Init(&myproc, info, 2);

PMIX_INFO_DESTRUCT(&info[0]);  // free the copied string
PMIX_INFO_DESTRUCT(&info[1]);  // free the copied string
\end{codepar}
\cspecificend

Moving to the Python version requires that the \refstruct{pmix_info_t} be translated to the Python \refpy{info} equivalent, and that the returned information be captured in the return parameters as opposed to a pointer parameter in the function call, as shown below:

\pyspecificstart
\begin{codepar}
import pmix
...

myclient = PMIxClient()
info = [\{'key':PMIX_PROGRAMMING_MODEL,
          'value':'TEST', 'val_type':PMIX_STRING\},
        \{'key':PMIX_MODEL_LIBRARY_NAME,
          'value':'PMIX', 'val_type':PMIX_STRING\}]
(rc,myproc) = myclient.init(info)
\end{codepar}
\pyspecificend

Note the use of the \refconst{PMIX_STRING} identifier to ensure the Python bindings interpret the provided string value as a \ac{PMIx} "string" and not an array of bytes.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Callback Function Definitions}
\label{app:python:fns}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{IOF Delivery Function}
\pylabel{iofcbfunc}
\declareapibinding{iofcbfunc}{pmix_iof_cbfunc_t}{Python}

%%%%
\summary

Callback function for delivering forwarded \ac{IO} to a process

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
def iofcbfunc(iofhdlr:integer, channel:bitarray,
              source:dict, payload:dict, info:list)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{iofhdlr}{Registration number of the handler being invoked (integer)}
\argin{channel}{Python \refpy{channel} 16-bit bitarray identifying the channel the data arrived on (bitarray)}
\argin{source}{Python \refpy{proc} identifying the namespace/rank of the process that generated the data (dict)}
\argin{payload}{Python \refpy{byteobject} containing the data (dict)}
\argin{info}{List of Python \refpy{info} provided by the source containing metadata about the payload. This could include \refattr{PMIX_IOF_COMPLETE} (list)}
\end{arglist}

Returns: nothing

See \refapi{pmix_iof_cbfunc_t} for details


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Event Handler}
\pylabel{evhandler}
\declareapibinding{evhandler}{pmix_notification_fn_t}{Python}

%%%%
\summary

Callback function for event handlers

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
def evhandler(evhdlr:integer, status:integer,
              source:dict, info:list, results:list)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{iofhdlr}{Registration number of the handler being invoked (integer)}
\argin{status}{Status associated with the operation (integer)}
\argin{source}{Python \refpy{proc} identifying the namespace/rank of the process that generated the event (dict)}
\argin{info}{List of Python \refpy{info} provided by the source containing metadata about the event (list)}
\argin{results}{List of Python \refpy{info} containing the aggregated results of all prior evhandlers (list)}
\end{arglist}

Returns:
\begin{itemize}
    \item \refarg{rc} - Status returned by the event handler's operation (integer)
    \item \refarg{results} - List of Python \refpy{info} containing results from this event handler's operation on the event (list)
\end{itemize}

See \refapi{pmix_notification_fn_t} for details


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Server Module Functions}
\pylabel{server module}

The following definitions represent functions that may be provided to the \ac{PMIx} server library at time of initialization for servicing of client requests. Module functions that are not provided default to returning "not supported" to the caller.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Client Connected}
\declareapibinding{clientconnected2}{pmix_server_client_connected2_fn_t}{Python}

%%%%
\summary

Notify the host server that a client connected to this server.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
def clientconnected2(proc:dict is not None, info:list)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{proc}{Python \refpy{proc} identifying the namespace/rank of the process that connected (dict)}
\argin{info}{list of Python \refpy{info} containing information about the process (list)}
\end{arglist}

Returns:
\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a \ac{PMIx} error code indicating the connection should be rejected (integer)
\end{itemize}

See \refapi{pmix_server_client_connected2_fn_t} for details


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Client Finalized}
\declareapibinding{clientfinalized}{pmix_server_client_finalized_fn_t}{Python}

%%%%
\summary

Notify the host environment that a client called \refapi{PMIx_Finalize}.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
def clientfinalized(proc:dict is not None):
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{proc}{Python \refpy{proc} identifying the namespace/rank of the process that finalized (dict)}
\end{arglist}

Returns: nothing

See \refapi{pmix_server_client_finalized_fn_t} for details


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Client Aborted}
\declareapibinding{clientaborted}{pmix_server_abort_fn_t}{Python}

%%%%
\summary

Notify the host environment that a local client called \refapi{PMIx_Abort}.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
def clientaborted(args:dict is not None)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{args}{Python dictionary containing:
    \begin{itemize}
        \item 'caller': Python \refpy{proc} identifying the namespace/rank of the process calling abort (dict)
        \item 'status': PMIx status  to be returned on exit (integer)
        \item 'msg': Optional string message to be printed (string)
        \item 'targets': Optional list of Python \refpy{proc} identifying the namespace/rank of the processes to be aborted (list)
    \end{itemize}}
\end{arglist}

Returns:
\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a \ac{PMIx} error code indicating the operation failed (integer)
\end{itemize}

See \refapi{pmix_server_abort_fn_t} for details


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Fence}
\declareapibinding{fence}{pmix_server_fencenb_fn_t}{Python}

%%%%
\summary

At least one client called either \refapi{PMIx_Fence} or \refapi{PMIx_Fence_nb}

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
def fence(args:dict is not None)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{args}{Python dictionary containing:
    \begin{itemize}
        \item 'procs': List of Python \refpy{proc} identifying the namespace/rank of the participating processes (list)
        \item 'directives': Optional list of Python \refpy{info} containing directives controlling the operation (list)
        \item 'data': Optional Python bytearray of data to be circulated during fence operation (bytearray)
    \end{itemize}}
\end{arglist}

Returns:
\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a \ac{PMIx} error code indicating the operation failed (integer)
    \item \refarg{data} - Python bytearray containing the aggregated data from all participants (bytearray)
\end{itemize}

See \refapi{pmix_server_fencenb_fn_t} for details


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Direct Modex}
\declareapibinding{dmodex}{pmix_server_dmodex_req_fn_t}{Python}

%%%%
\summary

Used by the PMIx server to request its local host contact the \ac{PMIx} server on the remote node that hosts the specified proc to obtain and return a direct modex blob for that proc.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
def dmodex(args:dict is not None)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{args}{Python dictionary containing:
    \begin{itemize}
        \item 'proc': Python \refpy{proc} of process whose data is being requested (dict)
        \item 'directives': Optional list of Python \refpy{info} containing directives controlling the operation (list)
    \end{itemize}}
\end{arglist}

Returns:
\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a \ac{PMIx} error code indicating the operation failed (integer)
    \item \refarg{data} - Python bytearray containing the data for the specified process (bytearray)
\end{itemize}

See \refapi{pmix_server_dmodex_req_fn_t} for details


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Publish}
\declareapibinding{publish}{pmix_server_publish_fn_t}{Python}

%%%%
\summary

Publish data per the PMIx API specification.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
def publish(args:dict is not None)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{args}{Python dictionary containing:
    \begin{itemize}
        \item 'proc': Python \refpy{proc} dictionary of process publishing the data (dict)
        \item 'directives': List of Python \refpy{info} containing data and directives (list)
    \end{itemize}}
\end{arglist}

Returns:
\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a \ac{PMIx} error code indicating the operation failed (integer)
\end{itemize}

See \refapi{pmix_server_publish_fn_t} for details


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Lookup}
\declareapibinding{lookup}{pmix_server_lookup_fn_t}{Python}

%%%%
\summary

Lookup published data.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
def lookup(args:dict is not None)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{args}{Python dictionary containing:
    \begin{itemize}
        \item 'proc': Python \refpy{proc} of process seeking the data (dict)
        \item 'keys': List of Python strings (list)
        \item 'directives': Optional list of Python \refpy{info} containing directives (list)
    \end{itemize}}
\end{arglist}

Returns:
\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a \ac{PMIx} error code indicating the operation failed (integer)
    \item \refarg{pdata} - List of \refpy{pdata} containing the returned results (list)
\end{itemize}

See \refapi{pmix_server_lookup_fn_t} for details


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Unpublish}
\declareapibinding{unpublish}{pmix_server_unpublish_fn_t}{Python}

%%%%
\summary

Delete data from the data store.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
def unpublish(args:dict is not None)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{args}{Python dictionary containing:
    \begin{itemize}
        \item 'proc': Python \refpy{proc} of process unpublishing data (dict)
        \item 'keys': List of Python strings (list)
        \item 'directives': Optional list of Python \refpy{info} containing directives (list)
    \end{itemize}}
\end{arglist}

Returns:
\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a \ac{PMIx} error code indicating the operation failed (integer)
\end{itemize}

See \refapi{pmix_server_unpublish_fn_t} for details


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Spawn}
\declareapibinding{spawn}{pmix_server_spawn_fn_t}{Python}

%%%%
\summary

Spawn a set of applications/processes as per the \refapi{PMIx_Spawn} API.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
def spawn(args:dict is not None)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{args}{Python dictionary containing:
    \begin{itemize}
        \item 'proc': Python \refpy{proc} of process making the request (dict)
        \item 'jobinfo': Optional list of Python \refpy{info} job-level directives and information (list)
        \item 'apps': List of Python \refpy{app} describing applications to be spawned (list)
    \end{itemize}}
\end{arglist}

Returns:
\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a \ac{PMIx} error code indicating the operation failed (integer)
    \item \refarg{nspace} - Python string containing namespace of the spawned job (str)
\end{itemize}

See \refapi{pmix_server_spawn_fn_t} for details


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Connect}
\declareapibinding{connect}{pmix_server_connect_fn_t}{Python}

%%%%
\summary

Record the specified processes as \textit{connected}.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
def connect(args:dict is not None)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{args}{Python dictionary containing:
    \begin{itemize}
        \item 'procs': List of Python \refpy{proc} identifying the namespace/rank of the participating processes (list)
        \item 'directives': Optional list of Python \refpy{info} containing directives controlling the operation (list)
    \end{itemize}}
\end{arglist}

Returns:
\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a \ac{PMIx} error code indicating the operation failed (integer)
\end{itemize}

See \refapi{pmix_server_connect_fn_t} for details


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Disconnect}
\declareapibinding{disconnect}{pmix_server_disconnect_fn_t}{Python}

%%%%
\summary

Disconnect a previously connected set of processes.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
def disconnect(args:dict is not None)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{args}{Python dictionary containing:
    \begin{itemize}
        \item 'procs': List of Python \refpy{proc} identifying the namespace/rank of the participating processes (list)
        \item 'directives': Optional list of Python \refpy{info} containing directives controlling the operation (list)
    \end{itemize}}
\end{arglist}

Returns:
\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a \ac{PMIx} error code indicating the operation failed (integer)
\end{itemize}

See \refapi{pmix_server_disconnect_fn_t} for details


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Register Events}
\declareapibinding{register_events}{pmix_server_register_events_fn_t}{Python}

%%%%
\summary

Register to receive notifications for the specified events.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
def register_events(args:dict is not None)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{args}{Python dictionary containing:
    \begin{itemize}
        \item 'codes': List of Python integers (list)
        \item 'directives': Optional list of Python \refpy{info} containing directives controlling the operation (list)
    \end{itemize}}
\end{arglist}

Returns:
\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a \ac{PMIx} error code indicating the operation failed (integer)
\end{itemize}

See \refapi{pmix_server_register_events_fn_t} for details


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Deregister Events}
\declareapibinding{deregister_events}{pmix_server_deregister_events_fn_t}{Python}

%%%%
\summary

Deregister to receive notifications for the specified events.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
def deregister_events(args:dict is not None)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{args}{Python dictionary containing:
    \begin{itemize}
        \item 'codes': List of Python integers (list)
    \end{itemize}}
\end{arglist}

Returns:
\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a \ac{PMIx} error code indicating the operation failed (integer)
\end{itemize}

See \refapi{pmix_server_deregister_events_fn_t} for details


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Notify Event}
\declareapibinding{notify_event}{pmix_server_notify_event_fn_t}{Python}

%%%%
\summary

Notify the specified range of processes of an event.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
def notify_event(args:dict is not None)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{args}{Python dictionary containing:
    \begin{itemize}
        \item 'code': Python integer \refstruct{pmix_status_t} (integer)
        \item 'source': Python \refpy{proc} of process that generated the event (dict)
        \item 'range': Python \refpy{range} in which the event is to be reported (integer)
        \item 'directives': Optional list of Python \refpy{info} directives (list)
    \end{itemize}}
\end{arglist}

Returns:
\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a \ac{PMIx} error code indicating the operation failed (integer)
\end{itemize}

See \refapi{pmix_server_notify_event_fn_t} for details


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Query}
\declareapibinding{query}{pmix_server_query_fn_t}{Python}

%%%%
\summary

Query information from the resource manager.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
def query(args:dict is not None)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{args}{Python dictionary containing:
    \begin{itemize}
        \item 'source': Python \refpy{proc} of requesting process (dict)
        \item 'queries': List of Python \refpy{query} directives (list)
    \end{itemize}}
\end{arglist}

Returns:
\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a \ac{PMIx} error code indicating the operation failed (integer)
    \item \refarg{info} - List of Python \refpy{info} containing the returned results (list)
\end{itemize}

See \refapi{pmix_server_query_fn_t} for details


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Tool Connected}
\declareapibinding{tool_connected}{pmix_server_tool_connection_fn_t}{Python}

%%%%
\summary

Register that a tool has connected to the server.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
def tool_connected(args:dict is not None)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{args}{Python dictionary containing:
    \begin{itemize}
        \item 'directives': Optional list of Python \refpy{info} info on the connecting tool (list)
    \end{itemize}}
\end{arglist}

Returns:
\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a \ac{PMIx} error code indicating the operation failed (integer)
    \item \refarg{proc} - Python \refpy{proc} containing the assigned namespace:rank for the tool (dict)
\end{itemize}

See \refapi{pmix_server_tool_connection_fn_t} for details


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Log}
\declareapibinding{log}{pmix_server_log_fn_t}{Python}

%%%%
\summary

Log data on behalf of a client.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
def log(args:dict is not None)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{args}{Python dictionary containing:
    \begin{itemize}
        \item 'source': Python \refpy{proc} of requesting process (dict)
        \item 'data': Optional list of Python \refpy{info} containing data to be logged (list)
        \item 'directives': Optional list of Python \refpy{info} containing directives (list)
    \end{itemize}}
\end{arglist}

Returns:
\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a \ac{PMIx} error code indicating the operation failed (integer)
\end{itemize}

See \refapi{pmix_server_log_fn_t} for details.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Allocate Resources}
\declareapibinding{allocate}{pmix_server_alloc_fn_t}{Python}

%%%%
\summary

Request allocation operations on behalf of a client.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
def allocate(args:dict is not None)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{args}{Python dictionary containing:
    \begin{itemize}
        \item 'source': Python \refpy{proc} of requesting process (dict)
        \item 'action': Python \refpy{allocdir} specifying requested action (integer)
        \item 'directives': Optional list of Python \refpy{info} containing directives (list)
    \end{itemize}}
\end{arglist}

Returns:
\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a \ac{PMIx} error code indicating the operation failed (integer)
    \item refarg{info} - List of Python \refpy{info} containing results of requested operation (list)
\end{itemize}

See \refapi{pmix_server_alloc_fn_t} for details.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Job Control}
\declareapibinding{job_control}{pmix_server_job_control_fn_t}{Python}

%%%%
\summary

Execute a job control action on behalf of a client.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
def job_control(args:dict is not None)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{args}{Python dictionary containing:
    \begin{itemize}
        \item 'source': Python \refpy{proc} of requesting process (dict)
        \item 'targets': List of Python \refpy{proc} specifying target processes (list)
        \item 'directives': Optional list of Python \refpy{info} containing directives (list)
    \end{itemize}}
\end{arglist}

Returns:
\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a \ac{PMIx} error code indicating the operation failed (integer)
\end{itemize}

See \refapi{pmix_server_job_control_fn_t} for details.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Monitor}
\declareapibinding{monitor}{pmix_server_monitor_fn_t}{Python}

%%%%
\summary

Request that a client be monitored for activity.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
def monitor(args:dict is not None)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{args}{Python dictionary containing:
    \begin{itemize}
        \item 'source': Python \refpy{proc} of requesting process (dict)
        \item 'monitor': Python \refpy{info} attribute indicating the type of monitor being requested (dict)
        \item 'error': Status code to be used when generating an event notification (integer) alerting that the monitor has been triggered.
        \item 'directives': Optional list of Python \refpy{info} containing directives (list)
    \end{itemize}}
\end{arglist}

Returns:
\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a \ac{PMIx} error code indicating the operation failed (integer)
\end{itemize}

See \refapi{pmix_server_monitor_fn_t} for details.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Get Credential}
\declareapibinding{get_credential}{pmix_server_get_cred_fn_t}{Python}

%%%%
\summary

Request a credential from the host environment.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
def get_credential(args:dict is not None)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{args}{Python dictionary containing:
    \begin{itemize}
        \item 'source': Python \refpy{proc} of requesting process (dict)
        \item 'directives': Optional list of Python \refpy{info} containing directives (list)
    \end{itemize}}
\end{arglist}

Returns:
\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a \ac{PMIx} error code indicating the operation failed (integer)
    \item \refarg{cred} - Python \refpy{byteobject} containing returned credential (dict)
    \item \refarg{info} - List of Python \refpy{info} containing any additional info about the credential (list)
\end{itemize}

See \refapi{pmix_server_get_cred_fn_t} for details.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Validate Credential}
\declareapibinding{validate_credential}{pmix_server_validate_cred_fn_t}{Python}

%%%%
\summary

Request validation of a credential

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
def validate_credential(args:dict is not None)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{args}{Python dictionary containing:
    \begin{itemize}
        \item 'source': Python \refpy{proc} of requesting process (dict)
        \item 'credential': Python \refpy{byteobject} containing credential (dict)
        \item 'directives': Optional list of Python \refpy{info} containing directives (list)
    \end{itemize}}
\end{arglist}

Returns:
\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a \ac{PMIx} error code indicating the operation failed (integer)
    \item \refarg{info} - List of Python \refpy{info} containing any additional info from the credential (list)
\end{itemize}

See \refapi{pmix_server_validate_cred_fn_t} for details.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{IO Forward}
\declareapibinding{iof_pull}{pmix_server_iof_fn_t}{Python}

%%%%
\summary

Request the specified IO channels be forwarded from the given array of processes.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
def iof_pull(args:dict is not None)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{args}{Python dictionary containing:
    \begin{itemize}
        \item 'sources': List of Python \refpy{proc} of processes  whose IO is being requested (list)
        \item 'channels': Bitmask of Python \refpy{channel} identifying IO channels to be forwarded (integer)
        \item 'directives': Optional list of Python \refpy{info} containing directives (list)
    \end{itemize}}
\end{arglist}

Returns:
\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a \ac{PMIx} error code indicating the operation failed (integer)
\end{itemize}

See \refapi{pmix_server_iof_fn_t} for details.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{IO Push}
\declareapibinding{iof_push}{pmix_server_stdin_fn_t}{Python}

%%%%
\summary

Pass standard input data to the host environment for transmission to specified recipients.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
def iof_push(args:dict is not None)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{args}{Python dictionary containing:
   \begin{itemize}
        \item 'source': Python \refpy{proc} of process whose input is being forwarded (dict)
        \item 'payload': Python \refpy{byteobject} containing input bytes (dict)
        \item 'targets': List of \refpy{proc} of processes that are to receive the payload (list)
        \item 'directives': Optional list of Python \refpy{info} containing directives (list)
    \end{itemize}}
\end{arglist}

Returns:
\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a \ac{PMIx} error code indicating the operation failed (integer)
\end{itemize}

See \refapi{pmix_server_stdin_fn_t} for details.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Group Operations}
\declareapibinding{group}{pmix_server_grp_fn_t}{Python}

%%%%
\summary

Request group operations (construct, destruct, etc.) on behalf of a set of processes.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
def group(args:dict is not None)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{args}{Python dictionary containing:
   \begin{itemize}
        \item 'op': Operation host is to perform on the specified group (integer)
        \item 'group': String identifier of target group (str)
        \item 'procs': List of Python \refpy{proc} of participating processes (dict)
        \item 'directives': Optional list of Python \refpy{info} containing directives (list)
    \end{itemize}}
\end{arglist}

Returns:
\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a \ac{PMIx} error code indicating the operation failed (integer)
    \item refarg{info} - List of Python \refpy{info} containing results of requested operation (list)
\end{itemize}

See \refapi{pmix_server_grp_fn_t} for details.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Fabric Operations}
\declareapibinding{fabric}{pmix_server_fabric_fn_t}{Python}

%%%%
\summary

Request fabric-related operations (e.g., information on a fabric) on behalf of a tool or other process.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
def fabric(args:dict is not None)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{args}{Python dictionary containing:
   \begin{itemize}
        \item 'source': Python \refpy{proc} of requesting process (dict)
        \item 'index': Identifier of the fabric being operated upon (integer)
        \item 'op': Operation host is to perform on the specified fabric (integer)
        \item 'directives': Optional list of Python \refpy{info} containing directives (list)
    \end{itemize}}
\end{arglist}

Returns:
\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a \ac{PMIx} error code indicating the operation failed (integer)
    \item refarg{info} - List of Python \refpy{info} containing results of requested operation (list)
\end{itemize}

See \refapi{pmix_server_fabric_fn_t} for details.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{PMIxClient}
\label{app:python:client}

The client Python class is by far the richest in terms of \acp{API} as it houses all the \acp{API} that an application might utilize. Due to the datatype translation requirements of the C-Python interface, only the blocking form of each \ac{API} is supported – providing a Python callback function directly to the C interface underlying the bindings was not a supportable option.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Client.init}
\declareapibinding{PMIxClient.init}{PMIx_Init}{Python}

\summary Initialize the \ac{PMIx} client library after obtaining a new PMIxClient object.

\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc, proc = myclient.init(info:list)
\end{codepar}
\pyspecificend


\begin{arglist}
\argin{info}{List of Python \refpy{info} dictionaries (list)}
\end{arglist}

Returns:

\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
    \item \refarg{proc} - a Python \refpy{proc} dictionary (dict)
\end{itemize}


See \refapi{PMIx_Init} for description of all relevant attributes and behaviors.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Client.initialized}
\declareapibinding{PMIxClient.initialized}{PMIx_Initialized}{Python}

\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc = myclient.initialized()
\end{codepar}
\pyspecificend

Returns:

\begin{itemize}
    \item \refarg{rc} - a value of \code{1} (true) will be returned if the \ac{PMIx} library has been initialized, and \code{0} (false) otherwise (integer)

\end{itemize}

See \refapi{PMIx_Initialized} for description of all relevant attributes and behaviors.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Client.get_version}
\declareapibinding{PMIxClient.get_version}{PMIx_Get_version}{Python}

\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
vers = myclient.get_version()
\end{codepar}
\pyspecificend

Returns:

\begin{itemize}
    \item \refarg{vers} - Python string containing the version of the \ac{PMIx} library (e.g., "3.1.4") (integer)

\end{itemize}

See \refapi{PMIx_Get_version} for description of all relevant attributes and behaviors.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Client.finalize}
\declareapibinding{PMIxClient.finalize}{PMIx_Finalize}{Python}

%%%%
\summary

Finalize the PMIx client library.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc = myclient.finalize(info:list)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{info}{List of Python \refpy{info} dictionaries (list)}
\end{arglist}

Returns:

\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
\end{itemize}

See \refapi{PMIx_Finalize} for description of all relevant attributes and behaviors.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Client.abort}
\declareapibinding{PMIxClient.abort}{PMIx_Abort}{Python}

%%%%
\summary

Request that the provided list of processes be aborted.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc = myclient.abort(status:integer, msg:str, targets:list)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{status}{PMIx status to be returned on exit (integer)}
\argin{msg}{String message to be printed (string)}
\argin{targets}{List of Python \refpy{proc} dictionaries (list)}
\end{arglist}

Returns:

\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
\end{itemize}

See \refapi{PMIx_Abort} for description of all relevant attributes and behaviors.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Client.store_internal}
\declareapibinding{PMIxClient.store_internal}{PMIx_Store_internal}{Python}

%%%%
\summary

Store some data locally for retrieval by other areas of the process

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc = myclient.store_internal(proc:dict, key:str, value:dict)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{proc}{Python \refpy{proc} dictionary of the process being referenced (dict)}
\argin{key}{String key of the data (string)}
\argin{value}{Python \refpy{value} dictionary (dict)}
\end{arglist}

Returns:

\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
\end{itemize}

See \refapi{PMIx_Store_internal} for details.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Client.put}
\declareapibinding{PMIxClient.put}{PMIx_Put}{Python}

%%%%
\summary

Push a key/value pair into the client's namespace.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc = myclient.put(scope:integer, key:str, value:dict)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{scope}{Scope of the data being posted (integer)}
\argin{key}{String key of the data (string)}
\argin{value}{Python \refpy{value} dictionary (dict)}
\end{arglist}

Returns:

\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
\end{itemize}

See \refapi{PMIx_Put} for description of all relevant attributes and behaviors.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Client.commit}
\declareapibinding{PMIxClient.commit}{PMIx_Commit}{Python}

%%%%
\summary

Push all previously \refapibinding{PMIxClient.put} values to the local PMIx server.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc = myclient.commit()
\end{codepar}
\pyspecificend

Returns:

\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
\end{itemize}

See \refapi{PMIx_Commit} for description of all relevant attributes and behaviors.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Client.fence}
\declareapibinding{PMIxClient.fence}{PMIx_Fence}{Python}

%%%%
\summary

Execute a blocking barrier across the processes identified in the specified list.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc = myclient.fence(peers:list, directives:list)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{peers}{List of Python \refpy{proc} dictionaries (list)}
\argin{directives}{List of Python \refpy{info} dictionaries (list)}
\end{arglist}

Returns:

\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
\end{itemize}

See \refapi{PMIx_Fence} for description of all relevant attributes and behaviors.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Client.get}
\declareapibinding{PMIxClient.get}{PMIx_Get}{Python}

%%%%
\summary

Retrieve a key/value pair.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc, val = myclient.get(proc:dict, key:str, directives:list)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{proc}{Python \refpy{proc} whose data is being requested (dict)}
\argin{key}{Python string key of the data to be returned (str)}
\argin{directives}{List of Python \refpy{info} dictionaries (list)}
\end{arglist}

Returns:

\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
    \item \refarg{val} - Python \refpy{value} containing the returned data (dict)
\end{itemize}

See \refapi{PMIx_Get} for description of all relevant attributes and behaviors.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Client.publish}
\declareapibinding{PMIxClient.publish}{PMIx_Publish}{Python}

%%%%
\summary

Publish data for later access via \refapi{PMIx_Lookup}.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc = myclient.publish(directives:list)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{directives}{List of Python \refpy{info} dictionaries containing data to be published and directives (list)}
\end{arglist}

Returns:

\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
\end{itemize}

See \refapi{PMIx_Publish} for description of all relevant attributes and behaviors.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Client.lookup}
\declareapibinding{PMIxClient.lookup}{PMIx_Lookup}{Python}

%%%%
\summary

Lookup information published by this or another process with \refapi{PMIx_Publish}.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc,info = myclient.lookup(pdata:list, directives:list)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{pdata}{List of Python \refpy{pdata} dictionaries identifying data to be retrieved (list)}
\argin{directives}{List of Python \refpy{info} dictionaries (list)}
\end{arglist}

Returns:

\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
    \item \refarg{info} - Python list of \refpy{info} containing the returned data (list)
\end{itemize}

See \refapi{PMIx_Lookup} for description of all relevant attributes and behaviors.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Client.unpublish}
\declareapibinding{PMIxClient.unpublish}{PMIx_Unpublish}{Python}

%%%%
\summary

Delete data published by this process with \refapi{PMIx_Publish}.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc = myclient.unpublish(keys:list, directives:list)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{keys}{List of Python string keys identifying data to be deleted (list)}
\argin{directives}{List of Python \refpy{info} dictionaries (list)}
\end{arglist}

Returns:

\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
\end{itemize}

See \refapi{PMIx_Unpublish} for description of all relevant attributes and behaviors.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Client.spawn}
\declareapibinding{PMIxClient.spawn}{PMIx_Spawn}{Python}

%%%%
\summary

Spawn a new job.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc,nspace = myclient.spawn(jobinfo:list, apps:list)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{jobinfo}{List of Python \refpy{info} dictionaries (list)}
\argin{apps}{List of Python \refpy{app} dictionaries (list)}
\end{arglist}

Returns:

\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
    \item \refarg{nspace} - Python \refpy{nspace} of the new job (dict)
\end{itemize}

See \refapi{PMIx_Spawn} for description of all relevant attributes and behaviors.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Client.connect}
\declareapibinding{PMIxClient.connect}{PMIx_Connect}{Python}

%%%%
\summary

Connect namespaces.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc = myclient.connect(peers:list, directives:list)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{peers}{List of Python \refpy{proc} dictionaries (list)}
\argin{directives}{List of Python \refpy{info} dictionaries (list)}
\end{arglist}

Returns:

\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
\end{itemize}

See \refapi{PMIx_Connect} for description of all relevant attributes and behaviors.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Client.disconnect}
\declareapibinding{PMIxClient.disconnect}{PMIx_Disconnect}{Python}

%%%%
\summary

Disconnect namespaces.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc = myclient.disconnect(peers:list, directives:list)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{peers}{List of Python \refpy{proc} dictionaries (list)}
\argin{directives}{List of Python \refpy{info} dictionaries (list)}
\end{arglist}

Returns:

\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
\end{itemize}

See \refapi{PMIx_Disconnect} for description of all relevant attributes and behaviors.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Client.resolve_peers}
\declareapibinding{PMIxClient.resolve_peers}{PMIx_Resolve_peers}{Python}

%%%%
\summary

Return list of processes within the specified \refpy{nspace} on the given node.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc,procs = myclient.resolve_peers(node:str, nspace:str)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{node}{Name of node whose processes are being requested (str)}
\argin{nspace}{Python \refpy{nspace} whose processes are to be returned (str)}
\end{arglist}

Returns:

\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
    \item \refarg{procs} - List of Python \refpy{proc} dictionaries (list)
\end{itemize}

See \refapi{PMIx_Resolve_peers} for description of all relevant attributes and behaviors.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Client.resolve_nodes}
\declareapibinding{PMIxClient.resolve_nodes}{PMIx_Resolve_nodes}{Python}

%%%%
\summary

Return list of nodes hosting processes within the specified \refpy{nspace}.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc,nodes = myclient.resolve_nodes(nspace:str)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{nspace}{Python \refpy{nspace} (str)}
\end{arglist}

Returns:

\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
    \item \refarg{nodes} - List of Python string node names (list)
\end{itemize}

See \refapi{PMIx_Resolve_nodes} for description of all relevant attributes and behaviors.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Client.query}
\declareapibinding{PMIxClient.query}{PMIx_Query_info}{Python}

%%%%
\summary

Query information about the system in general.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc,info = myclient.query(queries:list)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{queries}{List of Python \refpy{query} dictionaries (list)}
\end{arglist}

Returns:

\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
    \item \refarg{info} - List of Python \refpy{info} containing results of the query (list)
\end{itemize}

See \refapi{PMIx_Query_info} for description of all relevant attributes and behaviors.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Client.log}
\declareapibinding{PMIxClient.log}{PMIx_Log}{Python}

%%%%
\summary

Log data to a central data service/store.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc = myclient.log(data:list, directives:list)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{data}{List of Python \refpy{info} (list)}
\argin{directives}{Optional list of Python \refpy{info} (list)}
\end{arglist}

Returns:

\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
\end{itemize}

See \refapi{PMIx_Log} for description of all relevant attributes and behaviors.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Client.allocation_request}
\declareapibinding{PMIxClient.allocation_request}{PMIx_Allocation_request}{Python}

%%%%
\summary

Request an allocation operation from the host resource manager.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc,info = myclient.allocation_request(request:integer, directives:list)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{request}{Python \refpy{allocdir} specifying requested operation (integer)}
\argin{directives}{List of Python \refpy{info} describing request (list)}
\end{arglist}

Returns:

\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
    \item \refarg{info} - List of Python \refpy{info} containing results of the request (list)
\end{itemize}

See \refapi{PMIx_Allocation_request} for description of all relevant attributes and behaviors.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Client.job_ctrl}
\declareapibinding{PMIxClient.job_ctrl}{PMIx_Job_control}{Python}

%%%%
\summary

Request a job control action.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc,info = myclient.job_ctrl(targets:list, directives:list)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{targets}{List of Python \refpy{proc} specifying targets of requested operation (integer)}
\argin{directives}{List of Python \refpy{info} describing operation to be performed (list)}
\end{arglist}

Returns:

\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
    \item \refarg{info} - List of Python \refpy{info} containing results of the request (list)
\end{itemize}

See \refapi{PMIx_Job_control} for description of all relevant attributes and behaviors.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Client.monitor}
\declareapibinding{PMIxClient.monitor}{PMIx_Process_monitor}{Python}

%%%%
\summary

Request that something be monitored.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc,info = myclient.monitor(monitor:dict, error_code:integer, directives:list)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{monitor}{Python \refpy{info} specifying specifying the type of monitor being requested (dict)}
\argin{error_code}{Status code to be used when generating an event notification alerting that the monitor has been triggered (integer)}
\argin{directives}{List of Python \refpy{info} describing request (list)}
\end{arglist}

Returns:

\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
    \item \refarg{info} - List of Python \refpy{info} containing results of the request (list)
\end{itemize}

See \refapi{PMIx_Process_monitor} for description of all relevant attributes and behaviors.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Client.get_credential}
\declareapibinding{PMIxClient.get_credential}{PMIx_Get_credential}{Python}

%%%%
\summary

Request a credential from the PMIx server/SMS.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc,cred = myclient.get_credential(directives:list)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{directives}{Optional list of Python \refpy{info} describing request (list)}
\end{arglist}

Returns:

\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
    \item \refarg{cred} - Python \refpy{byteobject} containing returned credential (dict)
\end{itemize}

See \refapi{PMIx_Get_credential} for description of all relevant attributes and behaviors.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Client.validate_credential}
\declareapibinding{PMIxClient.validate_credential}{PMIx_Validate_credential}{Python}

%%%%
\summary

Request validation of a credential by the PMIx server/SMS.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc,info = myclient.validate_credential(cred:dict, directives:list)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{cred}{Python \refpy{byteobject} containing credential (dict)}
\argin{directives}{Optional list of Python \refpy{info} describing request (list)}
\end{arglist}

Returns:

\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
    \item \refarg{info} - List of Python \refpy{info} containing additional results of the request (list)
\end{itemize}

See \refapi{PMIx_Validate_credential} for description of all relevant attributes and behaviors.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Client.group_construct}
\declareapibinding{PMIxClient.group_construct}{PMIx_Group_construct}{Python}

%%%%
\summary

Construct a new group composed of the specified processes and identified with
the provided group identifier.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc,info = myclient.construct_group(grp:string,
                        members:list, directives:list)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{grp}{Python string identifier for the group (str)}
\argin{members}{List of Python \refpy{proc} dictionaries identifying group members (list)}
\argin{directives}{Optional list of Python \refpy{info} describing request (list)}
\end{arglist}

Returns:

\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
    \item \refarg{info} - List of Python \refpy{info} containing results of the request (list)
\end{itemize}

See \refapi{PMIx_Group_construct} for description of all relevant attributes and behaviors.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Client.group_invite}
\declareapibinding{PMIxClient.group_invite}{PMIx_Group_invite}{Python}

%%%%
\summary

Explicitly invite specified processes to join a group.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc,info = myclient.group_invite(grp:string,
                        members:list, directives:list)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{grp}{Python string identifier for the group (str)}
\argin{members}{List of Python \refpy{proc} dictionaries identifying processes to be invited (list)}
\argin{directives}{Optional list of Python \refpy{info} describing request (list)}
\end{arglist}

Returns:

\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
    \item \refarg{info} - List of Python \refpy{info} containing results of the request (list)
\end{itemize}

See \refapi{PMIx_Group_invite} for description of all relevant attributes and behaviors.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Client.group_join}
\declareapibinding{PMIxClient.group_join}{PMIx_Group_join}{Python}

%%%%
\summary

Respond to an invitation to join a group that is being asynchronously constructed.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc,info = myclient.group_join(grp:string,
                        leader:dict, opt:integer,
                        directives:list)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{grp}{Python string identifier for the group (str)}
\argin{leader}{Python \refpy{proc} dictionary identifying process leading the group (dict)}
\argin{opt}{One of the \refstruct{pmix_group_opt_t} values indicating decline/accept (integer)}
\argin{directives}{Optional list of Python \refpy{info} describing request (list)}
\end{arglist}

Returns:

\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
    \item \refarg{info} - List of Python \refpy{info} containing results of the request (list)
\end{itemize}

See \refapi{PMIx_Group_join} for description of all relevant attributes and behaviors.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Client.group_leave}
\declareapibinding{PMIxClient.group_leave}{PMIx_Group_leave}{Python}

%%%%
\summary

Leave a PMIx Group.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc = myclient.group_leave(grp:string, directives:list)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{grp}{Python string identifier for the group (str)}
\argin{directives}{Optional list of Python \refpy{info} describing request (list)}
\end{arglist}

Returns:

\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
\end{itemize}

See \refapi{PMIx_Group_leave} for description of all relevant attributes and behaviors.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Client.group_destruct}
\declareapibinding{PMIxClient.group_destruct}{PMIx_Group_destruct}{Python}

%%%%
\summary

Destruct a PMIx Group.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc = myclient.group_destruct(grp:string, directives:list)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{grp}{Python string identifier for the group (str)}
\argin{directives}{Optional list of Python \refpy{info} describing request (list)}
\end{arglist}

Returns:

\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
\end{itemize}

See \refapi{PMIx_Group_destruct} for description of all relevant attributes and behaviors.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Client.register_event_handler}
\declareapibinding{PMIxClient.register_event_handler}{PMIx_Register_event_handler}{Python}

%%%%
\summary

Register an event handler to report events.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc,id = myclient.register_event_handler(codes:list,
                        directives:list, cbfunc)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{codes}{List of Python integer status codes that should be reported to this handler (llist)}
\argin{directives}{Optional list of Python \refpy{info} describing request (list)}
\argin{cbfunc}{Python \refpy{evhandler} to be called when event is received (func)}
\end{arglist}

Returns:

\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
    \item \refarg{id} - \ac{PMIx} reference identifier for handler (integer)
\end{itemize}

See \refapi{PMIx_Register_event_handler} for description of all relevant attributes and behaviors.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Client.deregister_event_handler}
\declareapibinding{PMIxClient.deregister_event_handler}{PMIx_Deregister_event_handler}{Python}

%%%%
\summary

Deregister an event handler.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
myclient.deregister_event_handler(id:integer)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{id}{\ac{PMIx} reference identifier for handler (integer)}
\end{arglist}

Returns: None

See \refapi{PMIx_Deregister_event_handler} for description of all relevant attributes and behaviors.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Client.notify_event}
\declareapibinding{PMIxClient.notify_event}{PMIx_Notify_event}{Python}

%%%%
\summary

Report an event for notification via any registered handler.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc = myclient.notify_event(status:integer, source:dict,
                           range:integer, directives:list)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{status}{\ac{PMIx} status code indicating the event being reported (integer)}
\argin{source}{Python \refpy{proc} of the process that generated the event (dict)}
\argin{range}{Python \refpy{range} in which the event is to be reported (integer)}
\argin{directives}{Optional list of Python \refpy{info} dictionaries describing the event (list)}
\end{arglist}

Returns:
\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
\end{itemize}

See \refapi{PMIx_Notify_event} for description of all relevant attributes and behaviors.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Client.fabric_register}
\declareapibinding{PMIxClient.fabric_register}{PMIx_Fabric_register}{Python}

\summary
Register for access to fabric-related information, including communication cost matrix.

\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc,idx,fabricinfo = myclient.fabric_register(directives:list)
\end{codepar}
\pyspecificend


\begin{arglist}
\argin{directives}{Optional list of Python \refpy{info} containing directives (list)}
\end{arglist}

Returns:

\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
    \item \refarg{idx} - Index of the registered fabric (integer)
    \item \refarg{fabricinfo} - List of Python \refpy{info} containing fabric info (list)
\end{itemize}

See \refapi{PMIx_Fabric_register} for details.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Client.fabric_update}
\declareapibinding{PMIxClient.fabric_update}{PMIx_Fabric_update}{Python}

\summary
Update fabric-related information, including communication cost matrix.

\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc,fabricinfo = myclient.fabric_update(idx:integer)
\end{codepar}
\pyspecificend


\begin{arglist}
\argin{idx}{Index of the registered fabric (list)}
\end{arglist}

Returns:

\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
    \item \refarg{fabricinfo} - List of Python \refpy{info} containing updated fabric info (list)
\end{itemize}

See \refapi{PMIx_Fabric_update} for details.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Client.fabric_deregister}
\declareapibinding{PMIxClient.fabric_deregister}{PMIx_Fabric_deregister}{Python}

\summary
Deregister fabric.

\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc = myclient.fabric_deregister(idx:integer)
\end{codepar}
\pyspecificend


\begin{arglist}
\argin{idx}{Index of the registered fabric (list)}
\end{arglist}

Returns:

\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
\end{itemize}

See \refapi{PMIx_Fabric_deregister} for details.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Client.load_topology}
\declareapibinding{PMIxClient.load_topology}{PMIx_Load_topology}{Python}

\summary
Load the local hardware topology into the \ac{PMIx} library.

\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc = myclient.load_topology()
\end{codepar}
\pyspecificend

Returns:

\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
\end{itemize}

See \refapi{PMIx_Load_topology} for details - note that the topology loaded into the \ac{PMIx} library may be utilized by \ac{PMIx} and other libraries, but is not directly accessible by Python.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Client.get_relative_locality}
\declareapibinding{PMIxClient.get_relative_locality}{PMIx_Get_relative_locality}{Python}

\summary
Get the relative locality of two local processes.

\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc,locality = myclient.get_relative_locality(loc1:str, loc2:str)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{loc1}{Locality string of a process (str)}
\argin{loc2}{Locality string of a process (str)}
\end{arglist}


Returns:

\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
    \item \refarg{locality} - \refpy{locality} list containing the relative locality of the two processes (list)
\end{itemize}

See \refapi{PMIx_Get_relative_locality} for details.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Client.get_cpuset}
\declareapibinding{PMIxClient.get_cpuset}{PMIx_Get_cpuset}{Python}

\summary
Get the \ac{PU} binding bitmap of the current process.

\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc,cpuset = myclient.get_cpuset(ref:integer)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{ref}{\refpy{bindenv} binding envelope to be used (integer)}
\end{arglist}


Returns:

\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
    \item \refarg{cpuset} - \refpy{cpuset} containing the source and bitmap of the cpuset (dict)
\end{itemize}

See \refapi{PMIx_Get_cpuset} for details.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Client.parse_cpuset_string}
\declareapibinding{PMIxClient.parse_cpuset_string}{PMIx_Parse_cpuset_string}{Python}

\summary
Parse the \ac{PU} binding bitmap from its string representation.

\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc,cpuset = myclient.parse_cpuset_string(cpuset:string)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{cpuset}{String returned by \refapibinding{PMIxServer.generate_cpuset_string} (string)}
\end{arglist}


Returns:

\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
    \item \refarg{cpuset} - \refpy{cpuset} containing the source and bitmap of the cpuset (dict)
\end{itemize}

See \refapi{PMIx_Parse_cpuset_string} for details.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Client.compute_distances}
\declareapibinding{PMIxClient.compute_distances}{PMIx_Compute_distances}{Python}

\summary
Compute distances from specified process location to local devices.

\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc,distances = myclient.compute_distances(cpuset:dict, info:list)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{cpuset}{\refpy{cpuset} describing the location of the process (dict)}
\argin{info}{List of \refpy{info} dictionaries describing the devices whose distance is to be computed (list)}
\end{arglist}


Returns:

\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
    \item \refarg{distances} - List of \refpy{devdist} structures containing the distances from the caller to the specified devices (list)
\end{itemize}

See \refapi{PMIx_Compute_distances} for details. Note that distances can only be computed against the local topology.



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Client.error_string}
\declareapibinding{PMIxClient.error_string}{PMIx_Error_string}{Python}

%%%%
\summary

Pretty-print string representation of \refstruct{pmix_status_t}.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rep = myclient.error_string(status:integer)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{status}{\ac{PMIx} status code (integer)}
\end{arglist}

Returns:
\begin{itemize}
    \item \refarg{rep} - String representation of the provided status code (str)
\end{itemize}

See \refapi{PMIx_Error_string} for further details.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Client.proc_state_string}
\declareapibinding{PMIxClient.proc_state_string}{PMIx_Proc_state_string}{Python}

%%%%
\summary

Pretty-print string representation of \refstruct{pmix_proc_state_t}.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rep = myclient.proc_state_string(state:integer)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{state}{\ac{PMIx} process state code (integer)}
\end{arglist}

Returns:
\begin{itemize}
    \item \refarg{rep} - String representation of the provided process state (str)
\end{itemize}

See \refapi{PMIx_Proc_state_string} for further details.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Client.scope_string}
\declareapibinding{PMIxClient.scope_string}{PMIx_Scope_string}{Python}

%%%%
\summary

Pretty-print string representation of \refstruct{pmix_scope_t}.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rep = myclient.scope_string(scope:integer)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{scope}{\ac{PMIx} scope value (integer)}
\end{arglist}

Returns:
\begin{itemize}
    \item \refarg{rep} - String representation of the provided scope (str)
\end{itemize}

See \refapi{PMIx_Scope_string} for further details


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Client.persistence_string}
\declareapibinding{PMIxClient.persistence_string}{PMIx_Persistence_string}{Python}

%%%%
\summary

Pretty-print string representation of \refstruct{pmix_persistence_t}.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rep = myclient.persistence_string(persistence:integer)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{persistence}{\ac{PMIx} persistence value (integer)}
\end{arglist}

Returns:
\begin{itemize}
    \item \refarg{rep} - String representation of the provided persistence (str)
\end{itemize}

See \refapi{PMIx_Persistence_string} for further details.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Client.data_range_string}
\declareapibinding{PMIxClient.data_range_string}{PMIx_Data_range_string}{Python}

%%%%
\summary

Pretty-print string representation of \refstruct{pmix_data_range_t}.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rep = myclient.data_range_string(range:integer)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{range}{\ac{PMIx} data range value (integer)}
\end{arglist}

Returns:
\begin{itemize}
    \item \refarg{rep} - String representation of the provided data range (str)
\end{itemize}

See \refapi{PMIx_Data_range_string} for further details.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Client.info_directives_string}
\declareapibinding{PMIxClient.info_directives_string}{PMIx_Info_directives_string}{Python}

%%%%
\summary

Pretty-print string representation of \refstruct{pmix_info_directives_t}.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rep = myclient.info_directives_string(directives:bitarray)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{directives}{\ac{PMIx} \refpy{info directives} value (bitarray)}
\end{arglist}

Returns:
\begin{itemize}
    \item \refarg{rep} - String representation of the provided info directives (str)
\end{itemize}

See \refapi{PMIx_Info_directives_string} for further details.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Client.data_type_string}
\declareapibinding{PMIxClient.data_type_string}{PMIx_Data_type_string}{Python}

%%%%
\summary

Pretty-print string representation of \refstruct{pmix_data_type_t}.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rep = myclient.data_type_string(dtype:integer)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{dtype}{\ac{PMIx} datatype value (integer)}
\end{arglist}

Returns:
\begin{itemize}
    \item \refarg{rep} - String representation of the provided datatype (str)
\end{itemize}

See \refapi{PMIx_Data_type_string} for further details.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Client.alloc_directive_string}
\declareapibinding{PMIxClient.alloc_directive_string}{PMIx_Alloc_directive_string}{Python}

%%%%
\summary

Pretty-print string representation of \refstruct{pmix_alloc_directive_t}.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rep = myclient.alloc_directive_string(adir:integer)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{adir}{\ac{PMIx} allocation directive value (integer)}
\end{arglist}

Returns:
\begin{itemize}
    \item \refarg{rep} - String representation of the provided allocation directive (str)
\end{itemize}

See \refapi{PMIx_Alloc_directive_string} for further details.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Client.iof_channel_string}
\declareapibinding{PMIxClient.iof_channel_string}{PMIx_IOF_channel_string}{Python}

%%%%
\summary

Pretty-print string representation of \refstruct{pmix_iof_channel_t}.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rep = myclient.iof_channel_string(channel:bitarray)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{channel}{\ac{PMIx} IOF \refpy{channel} value (bitarray)}
\end{arglist}

Returns:
\begin{itemize}
    \item \refarg{rep} - String representation of the provided IOF channel (str)
\end{itemize}

See \refapi{PMIx_IOF_channel_string} for further details.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Client.job_state_string}
\declareapibinding{PMIxClient.job_state_string}{PMIx_Job_state_string}{Python}

%%%%
\summary

Pretty-print string representation of \refstruct{pmix_job_state_t}.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rep = myclient.job_state_string(state:integer)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{state}{\ac{PMIx} job state value (integer)}
\end{arglist}

Returns:
\begin{itemize}
    \item \refarg{rep} - String representation of the provided job state (str)
\end{itemize}

See \refapi{PMIx_Job_state_string} for further details.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Client.get_attribute_string}
\declareapibinding{PMIxClient.get_attribute_string}{PMIx_Get_attribute_string}{Python}

%%%%
\summary

Pretty-print string representation of a \ac{PMIx} attribute.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rep = myclient.get_attribute_string(attribute:str)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{attribute}{\ac{PMIx} attribute name (string)}
\end{arglist}

Returns:
\begin{itemize}
    \item \refarg{rep} - String representation of the provided attribute (str)
\end{itemize}

See \refapi{PMIx_Get_attribute_string} for further details.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Client.get_attribute_name}
\declareapibinding{PMIxClient.get_attribute_name}{PMIx_Get_attribute_name}{Python}

%%%%
\summary

Pretty-print name of a \ac{PMIx} attribute corresponding to the provided string.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rep = myclient.get_attribute_name(attribute:str)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{attributestring}{Attribute string (string)}
\end{arglist}

Returns:
\begin{itemize}
    \item \refarg{rep} - Attribute name corresponding to the provided string (str)
\end{itemize}

See \refapi{PMIx_Get_attribute_name} for further details.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Client.link_state_string}
\declareapibinding{PMIxClient.link_state_string}{PMIx_Link_state_string}{Python}

%%%%
\summary

Pretty-print string representation of \refstruct{pmix_link_state_t}.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rep = myclient.link_state_string(state:integer)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{state}{\ac{PMIx} link state value (integer)}
\end{arglist}

Returns:
\begin{itemize}
    \item \refarg{rep} - String representation of the provided link state (str)
\end{itemize}

See \refapi{PMIx_Link_state_string} for further details.



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Client.device_type_string}
\declareapibinding{PMIxClient.device_type_string}{PMIx_Device_type_string}{Python}

%%%%
\summary

Pretty-print string representation of \refstruct{pmix_device_type_t}.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rep = myclient.device_type_string(type:bitarray)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{type}{\ac{PMIx} device type value (bitarray)}
\end{arglist}

Returns:
\begin{itemize}
    \item \refarg{rep} - String representation of the provided device type (str)
\end{itemize}

See \refapi{PMIx_Device_type_string} for further details.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Client.progress}
\declareapibinding{PMIxClient.progress}{PMIx_Progress}{Python}

%%%%
\summary

Progress the \ac{PMIx} library.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
myclient.progress()
\end{codepar}
\pyspecificend


See \refapi{PMIx_Progress} for further details.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{PMIxServer}
\label{app:python:server}

The server Python class inherits the Python "client" class as its parent. Thus, it includes all client functions in addition to the ones defined in this section.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Server.init}
\declareapibinding{PMIxServer.init}{PMIx_server_init}{Python}

\summary Initialize the \ac{PMIx} server library after obtaining a new PMIxServer object.

\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc = myserver.init(directives:list, map:dict)
\end{codepar}
\pyspecificend


\begin{arglist}
\argin{directives}{List of Python \refpy{info} dictionaries (list)}
\argin{map}{Python dictionary key-function pairs that map \refpy{server module} callback functions to provided implementations (see \refapi{pmix_server_module_t}) (dict)}
\end{arglist}

Returns:

\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
\end{itemize}

See \refapi{PMIx_server_init} for description of all relevant attributes and behaviors.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Server.finalize}
\declareapibinding{PMIxServer.finalize}{PMIx_server_finalize}{Python}

\summary Finalize the \ac{PMIx} server library.

\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc = myserver.finalize()
\end{codepar}
\pyspecificend


Returns:

\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
\end{itemize}

See \refapi{PMIx_server_finalize} for details.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Server.generate_regex}
\declareapibinding{PMIxServer.generate_regex}{PMIx_generate_regex}{Python}

\summary
Generate a regular expression representation of the input strings.

\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc,regex = myserver.generate_regex(input:list)
\end{codepar}
\pyspecificend


\begin{arglist}
\argin{input}{List of Python strings (e.g., node names)  (list)}
\end{arglist}

Returns:

\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
    \item \refarg{regex} - Python \code{bytearray} containing regular expression representation of the input list (\code{bytearray})
\end{itemize}

See \refapi{PMIx_generate_regex} for details.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Server.generate_ppn}
\declareapibinding{PMIxServer.generate_ppn}{PMIx_generate_ppn}{Python}

\summary
Generate a regular expression representation of the input strings.

\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc,regex = myserver.generate_ppn(input:list)
\end{codepar}
\pyspecificend


\begin{arglist}
\argin{input}{List of Python strings, each string consisting of a comma-delimited list of ranks on each node, with the strings being in the same order as the node names provided to "generate_regex" (list)}
\end{arglist}

Returns:

\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
    \item \refarg{regex} - Python \code{bytearray} containing regular expression representation of the input list (\code{bytearray})
\end{itemize}

See \refapi{PMIx_generate_ppn} for details.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Server.generate_locality_string}
\declareapibinding{PMIxServer.generate_locality_string}{PMIx_server_generate_locality_string}{Python}

\summary
Generate a PMIx locality string from a given cpuset.

\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc,locality = myserver.generate_locality_string(cpuset:dict)
\end{codepar}
\pyspecificend


\begin{arglist}
\argin{cset}{\refpy{cpuset} containing the bitmap of assigned PUs (dict)}
\end{arglist}

Returns:

\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
    \item \refarg{locality} - String representation of the PMIx locality corresponding to the input bitmap (string)
\end{itemize}

See \refapi{PMIx_server_generate_locality_string} for details.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Server.generate_cpuset_string}
\declareapibinding{PMIxServer.generate_cpuset_string}{PMIx_server_generate_cpuset_string}{Python}

\summary
Generate a PMIx string representation of the provided cpuset.

\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc,cpustr = myserver.generate_cpuset_string(cpuset:dict)
\end{codepar}
\pyspecificend


\begin{arglist}
\argin{cset}{\refpy{cpuset} containing the bitmap of assigned PUs (dict)}
\end{arglist}

Returns:

\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
    \item \refarg{cpustr} - String representation of the input bitmap (string)
\end{itemize}

See \refapi{PMIx_server_generate_cpuset_string} for details.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Server.register_nspace}
\declareapibinding{PMIxServer.register_nspace}{PMIx_server_register_nspace}{Python}

\summary Setup the data about a particular namespace.

\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc = myserver.register_nspace(nspace:str,
                              nlocalprocs:integer,
                              directives:list)
\end{codepar}
\pyspecificend


\begin{arglist}
\argin{nspace}{Python string containing the namespace (str)}
\argin{nlocalprocs}{Number of local processes (integer)}
\argin{directives}{List of Python \refpy{info} dictionaries (list)}
\end{arglist}

Returns:

\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
\end{itemize}

See \refapi{PMIx_server_register_nspace} for description of all relevant attributes and behaviors.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Server.deregister_nspace}
\declareapibinding{PMIxServer.deregister_nspace}{PMIx_server_deregister_nspace}{Python}

\summary

Deregister a namespace.

\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
myserver.deregister_nspace(nspace:str)
\end{codepar}
\pyspecificend


\begin{arglist}
\argin{nspace}{Python string containing the namespace (str)}
\end{arglist}

Returns: None

See \refapi{PMIx_server_deregister_nspace} for details.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Server.register_resources}
\declareapibinding{PMIxServer.register_resources}{PMIx_server_register_resources}{Python}

\summary

Register non-namespace related information with the local \ac{PMIx} library

\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
myserver.register_resources(directives:list)
\end{codepar}
\pyspecificend


\begin{arglist}
\argin{directives}{List of Python \refpy{info} dictionaries (list)}
\end{arglist}

Returns: None

See \refapi{PMIx_server_register_resources} for details.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Server.deregister_resources}
\declareapibinding{PMIxServer.deregister_resources}{PMIx_server_deregister_resources}{Python}

\summary

Remove non-namespace related information from the local \ac{PMIx} library

\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
myserver.deregister_resources(directives:list)
\end{codepar}
\pyspecificend


\begin{arglist}
\argin{directives}{List of Python \refpy{info} dictionaries (list)}
\end{arglist}

Returns: None

See \refapi{PMIx_server_deregister_resources} for details.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Server.register_client}
\declareapibinding{PMIxServer.register_client}{PMIx_server_register_client}{Python}

\summary
Register a client process with the PMIx server library.

\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc = myserver.register_client(proc:dict, uid:integer, gid:integer)
\end{codepar}
\pyspecificend


\begin{arglist}
\argin{proc}{Python \refpy{proc} dictionary identifying the client process (dict)}
\argin{uid}{Linux uid value for user executing client process (integer)}
\argin{gid}{Linux gid value for user executing client process (integer)}
\end{arglist}

Returns:

\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
\end{itemize}

See \refapi{PMIx_server_register_client} for details.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Server.deregister_client}
\declareapibinding{PMIxServer.deregister_client}{PMIx_server_deregister_client}{Python}

\summary
Deregister a client process and purge all data relating to it.


\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
myserver.deregister_client(proc:dict)
\end{codepar}
\pyspecificend


\begin{arglist}
\argin{proc}{Python \refpy{proc} dictionary identifying the client process (dict)}
\end{arglist}

Returns: None

See \refapi{PMIx_server_deregister_client} for details.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Server.setup_fork}
\declareapibinding{PMIxServer.setup_fork}{PMIx_server_setup_fork}{Python}

\summary
Setup the environment of a child process that is to be forked
by the host.

\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc = myserver.setup_fork(proc:dict, envin:dict)
\end{codepar}
\pyspecificend


\begin{arglist}
\argin{proc}{Python \refpy{proc} dictionary identifying the client process (dict)}
\arginout{envin}{Python dictionary containing the environment to be passed to the client (dict)}
\end{arglist}

Returns:

\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
\end{itemize}

See \refapi{PMIx_server_setup_fork} for details.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Server.dmodex_request}
\declareapibinding{PMIxServer.dmodex_request}{PMIx_server_dmodex_request}{Python}

\summary
Function by which the host server can request modex data from the local PMIx server.

\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc,data = myserver.dmodex_request(proc:dict)
\end{codepar}
\pyspecificend


\begin{arglist}
\argin{proc}{Python \refpy{proc} dictionary identifying the process whose data is requested (dict)}
\end{arglist}

Returns:

\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
    \item \refarg{data} - Python \refpy{byteobject} containing the returned data (dict)
\end{itemize}

See \refapi{PMIx_server_dmodex_request} for details.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Server.setup_application}
\declareapibinding{PMIxServer.setup_application}{PMIx_server_setup_application}{Python}

\summary
Function by which the resource manager can request application-specific setup data prior to launch of a \refterm{job}.

\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc,info = myserver.setup_application(nspace:str, directives:list)
\end{codepar}
\pyspecificend


\begin{arglist}
\argin{nspace}{Namespace whose setup information is being requested (str)}
\argin{directives}{Python list of \refpy{info} directives}
\end{arglist}

Returns:

\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
    \item \refarg{info} - Python list of \refpy{info} dictionaries containing the returned data (list)
\end{itemize}

See \refapi{PMIx_server_setup_application} for details.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Server.register_attributes}
\declareapibinding{PMIxServer.register_attributes}{PMIx_Register_attributes}{Python}

\summary
Register host environment attribute support for a function.

\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc = myserver.register_attributes(function:str, attrs:list)
\end{codepar}
\pyspecificend


\begin{arglist}
\argin{function}{Name of the function (str)}
\argin{attrs}{Python list of \refpy{regattr} describing the supported attributes}
\end{arglist}

Returns:

\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
\end{itemize}

See \refapi{PMIx_Register_attributes} for details.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Server.setup_local_support}
\declareapibinding{PMIxServer.setup_local_support}{PMIx_server_setup_local_support}{Python}

\summary
Function by which the local \ac{PMIx} server can perform any application-specific operations prior to spawning local clients of a given application.

\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc = myserver.setup_local_support(nspace:str, info:list)
\end{codepar}
\pyspecificend


\begin{arglist}
\argin{nspace}{Namespace whose setup information is being requested (str)}
\argin{info}{Python list of \refpy{info} containing the setup data (list)}
\end{arglist}

Returns:

\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
\end{itemize}

See \refapi{PMIx_server_setup_local_support} for details.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Server.iof_deliver}
\declareapibinding{PMIxServer.iof_deliver}{PMIx_server_IOF_deliver}{Python}

\summary
Function by which the host environment can pass forwarded \ac{IO} to the \ac{PMIx} server library for distribution to its clients.

\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc = myserver.iof_deliver(source:dict, channel:integer,
                          data:dict, directives:list)
\end{codepar}
\pyspecificend


\begin{arglist}
\argin{source}{Python \refpy{proc} dictionary identifying the process who generated the data (dict)}
\argin{channel}{Python \refpy{channel} bitmask identifying IO channel of the provided data (integer)}
\argin{data}{Python \refpy{byteobject} containing the data (dict)}
\argin{directives}{Python list of \refpy{info} containing directives (list)}
\end{arglist}

Returns:

\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
\end{itemize}

See \refapi{PMIx_server_IOF_deliver} for details.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Server.collect_inventory}
\declareapibinding{PMIxServer.collect_inventory}{PMIx_server_collect_inventory}{Python}

\summary
Collect inventory of resources on a node.

\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc,info = myserver.collect_inventory(directives:list)
\end{codepar}
\pyspecificend


\begin{arglist}
\argin{directives}{Optional Python list of \refpy{info} containing directives (list)}
\end{arglist}

Returns:

\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
    \item \refarg{info} - Python list of \refpy{info} containing the returned data (list)
\end{itemize}

See \refapi{PMIx_server_collect_inventory} for details.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Server.deliver_inventory}
\declareapibinding{PMIxServer.deliver_inventory}{PMIx_server_deliver_inventory}{Python}

\summary
Pass collected inventory to the \ac{PMIx} server library for storage.

\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc = myserver.deliver_inventory(info:list, directives:list)
\end{codepar}
\pyspecificend


\begin{arglist}
\argin{info} - Python list of \refpy{info} dictionaries containing the inventory data (list)
\argin{directives}{Python list of \refpy{info} dictionaries containing directives (list)}
\end{arglist}

Returns:

\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
\end{itemize}

See \refapi{PMIx_server_deliver_inventory} for details.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Server.define_process_set}
\declareapibinding{PMIxServer.define_process_set}{PMIx_server_define_process_set}{Python}

\summary
Add members to a \ac{PMIx} process set.

\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc = myserver.define_process_set(members:list, name:str)
\end{codepar}
\pyspecificend


\begin{arglist}
\argin{members} - List of Python \refpy{proc} dictionaries identifying the processes to be added to the process set (list)
\argin{name} - Name of the process set (str)
\end{arglist}

Returns:

\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
\end{itemize}

See \refapi{PMIx_server_define_process_set} for details.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Server.delete_process_set}
\declareapibinding{PMIxServer.delete_process_set}{PMIx_server_delete_process_set}{Python}

\summary
Delete a \ac{PMIx} process set.

\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc = myserver.delete_process_set(name:str)
\end{codepar}
\pyspecificend


\begin{arglist}
\argin{name} - Name of the process set (str)
\end{arglist}

Returns:

\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
\end{itemize}

See \refapi{PMIx_server_delete_process_set} for details.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Server.register_resources}
\declareapibinding{PMIxServer.register_resources}{PMIx_server_register_resources}{Python}

\summary
Register non-namespace related information with the local \ac{PMIx} server library.

\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc = myserver.register_resources(info:list)
\end{codepar}
\pyspecificend


\begin{arglist}
\argin{info} - List of Python \refpy{info} dictionaries list)
\end{arglist}

Returns:

\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
\end{itemize}

See \refapi{PMIx_server_register_resources} for details.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Server.deregister_resources}
\declareapibinding{PMIxServer.deregister_resources}{PMIx_server_deregister_resources}{Python}

\summary
Deregister non-namespace related information with the local \ac{PMIx} server library.

\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc = myserver.deregister_resources(info:list)
\end{codepar}
\pyspecificend


\begin{arglist}
\argin{info} - List of Python \refpy{info} dictionaries list)
\end{arglist}

Returns:

\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
\end{itemize}

See \refapi{PMIx_server_deregister_resources} for details.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{PMIxTool}
\label{app:python:tool}

The tool Python class inherits the Python "server" class as its parent. Thus, it includes all client and server functions in addition to the ones defined in this section.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Tool.init}
\declareapibinding{PMIxTool.init}{PMIx_tool_init}{Python}

\summary

Initialize the \ac{PMIx} tool library after obtaining a new PMIxTool object.

\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc,proc = mytool.init(info:list)
\end{codepar}
\pyspecificend


\begin{arglist}
\argin{info}{List of Python \refpy{info} directives (list)}
\end{arglist}

Returns:

\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
    \item \refarg{proc} - a Python \refpy{proc} (dict)
\end{itemize}

See \refapi{PMIx_tool_init} for description of all relevant attributes and behaviors.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Tool.finalize}
\declareapibinding{PMIxTool.finalize}{PMIx_tool_finalize}{Python}

\summary

Finalize the PMIx tool library, closing the connection to the server.

\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc = mytool.finalize()
\end{codepar}
\pyspecificend


Returns:

\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
\end{itemize}


See \refapi{PMIx_tool_finalize} for description of all relevant attributes and behaviors.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Tool.disconnect}
\declareapibinding{PMIxTool.disconnect}{PMIx_tool_disconnect}{Python}

\summary

Disconnect the \ac{PMIx} tool from the specified server connection while leaving the tool library initialized.

\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc = mytool.disconnect(server:dict)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{server}{Process identifier of server from which the tool is to be disconnected (\refpy{proc})}
\end{arglist}

Returns:

\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
\end{itemize}

See \refapi{PMIx_tool_disconnect} for details.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Tool.attach_to_server}
\declareapibinding{PMIxTool.attach_to_server}{PMIx_tool_attach_to_server}{Python}

\summary
Establish a connection to a PMIx server.

\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc,proc,server = mytool.connect_to_server(info:list)
\end{codepar}
\pyspecificend


\begin{arglist}
\argin{info}{List of Python \refpy{info} dictionaries (list)}
\end{arglist}

Returns:

\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
    \item \refarg{proc} - a Python \refpy{proc} containing the tool's identifier (dict)
    \item \refarg{server} - a Python \refpy{proc} containing the identifier of the server to which the tool attached (dict)
\end{itemize}

See \refapi{PMIx_tool_attach_to_server} for details.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Tool.get_servers}
\declareapibinding{PMIxTool.get_servers}{PMIx_tool_get_servers}{Python}

\summary
Get a list containing the \refpy{proc} process identifiers of all servers to which the tool is currently connected.


\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc,servers = mytool.get_servers()
\end{codepar}
\pyspecificend

Returns:

\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
    \item \refarg{servers} - a list of Python \refpy{proc} containing the identifiers of the servers to which the tool is currently attached (dict)
\end{itemize}

See \refapi{PMIx_tool_get_servers} for details.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Tool.set_server}
\declareapibinding{PMIxTool.set_server}{PMIx_tool_set_server}{Python}

\summary
Designate a server as the tool's \emph{primary} server.


\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc = mytool.set_server(proc:dict, info:list)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{proc}{Python \refpy{proc} containing the identifier of the servers to which the tool is to attach  (list)}
\argin{info}{List of Python \refpy{info} dictionaries (list)}
\end{arglist}

Returns:

\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
\end{itemize}

See \refapi{PMIx_tool_set_server} for details.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Tool.iof_pull}
\declareapibinding{PMIxTool.iof_pull}{PMIx_IOF_pull}{Python}

%%%%
\summary

Register to receive output forwarded from a remote process.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc,id = mytool.iof_pull(sources:list, channel:integer,
                        directives:list, cbfunc)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{sources}{List of Python \refpy{proc} dictionaries of processes whose IO is being requested (list)}
\argin{channel}{Python \refpy{channel} bitmask identifying IO channels to be forwarded (integer)}
\argin{directives}{List of Python \refpy{info} dictionaries describing request (list)}
\argin{cbfunc}{Python \refpy{iofcbfunc} to receive IO payloads (func)}
\end{arglist}

Returns:

\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
    \item \refarg{id} - \ac{PMIx} reference identifier for request (integer)
\end{itemize}

See \refapi{PMIx_IOF_pull} for description of all relevant attributes and behaviors.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Tool.iof_deregister}
\declareapibinding{PMIxTool.iof_deregister}{PMIx_IOF_deregister}{Python}

%%%%
\summary

Deregister from output forwarded from a remote process.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc = mytool.iof_deregister(id:integer, directives:list)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{id}{\ac{PMIx} reference identifier returned by pull request (list)}
\argin{directives}{List of Python \refpy{info} dictionaries describing request (list)}
\end{arglist}

Returns:

\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
\end{itemize}

See \refapi{PMIx_IOF_deregister} for description of all relevant attributes and behaviors.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Tool.iof_push}
\declareapibinding{PMIxTool.iof_push}{PMIx_IOF_push}{Python}

%%%%
\summary

Push data collected locally (typically from stdin) to
stdin of target recipients.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc = mytool.iof_push(targets:list, data:dict, directives:list)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{sources}{List of Python \refpy{proc} of target processes (list)}
\argin{data}{Python \refpy{byteobject} containing data to be delivered (dict)}
\argin{directives}{Optional list of Python \refpy{info} describing request (list)}
\end{arglist}

Returns:

\begin{itemize}
    \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
\end{itemize}

See \refapi{PMIx_IOF_push} for description of all relevant attributes and behaviors.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Example Usage}
\label{app:python:examples}

The following examples are provided to illustrate the use of the Python bindings.

\subsection{Python Client}

The following example contains a client program that illustrates a fairly common usage pattern. The program instantiates and initializes the PMIxClient class, posts some data that is to be shared across all processes in the job, executes a “fence” that circulates the data, and then retrieves a value posted by one of its peers. Note that the example has been formatted to fit the document layout.


\pyspecificstart
\begin{codepar}
from pmix import *

def main():
    # Instantiate a client object
    myclient = PMIxClient()
    print("Testing PMIx ", myclient.get_version())

    # Initialize the PMIx client library, declaring the programming model
    # as “TEST” and the library name as “PMIX”, just for the example
    info = [{'key':PMIX_PROGRAMMING_MODEL,
             'value':'TEST', 'val_type':PMIX_STRING},
            {'key':PMIX_MODEL_LIBRARY_NAME,
             'value':'PMIX', 'val_type':PMIX_STRING}]
    rc,myname = myclient.init(info)
    if PMIX_SUCCESS != rc:
        print("FAILED TO INIT WITH ERROR", myclient.error_string(rc))
        exit(1)

    # try posting a value
    rc = myclient.put(PMIX_GLOBAL, "mykey",
                      {'value':1, 'val_type':PMIX_INT32})
    if PMIX_SUCCESS != rc:
        print("PMIx_Put FAILED WITH ERROR", myclient.error_string(rc))
        # cleanly finalize
        myclient.finalize()
        exit(1)

    # commit it
    rc = myclient.commit()
    if PMIX_SUCCESS != rc:
        print("PMIx_Commit FAILED WITH ERROR",
              myclient.error_string(rc))
        # cleanly finalize
        myclient.finalize()
        exit(1)

    # execute fence across all processes in my job
    procs = []
    info = []
    rc = myclient.fence(procs, info)
    if PMIX_SUCCESS != rc:
        print("PMIx_Fence FAILED WITH ERROR", myclient.error_string(rc))
        # cleanly finalize
        myclient.finalize()
        exit(1)

    # Get a value from a peer
    if 0 != myname['rank']:
        info = []
        rc, get_val = myclient.get({'nspace':"testnspace", 'rank': 0},
                                   "mykey", info)
        if PMIX_SUCCESS != rc:
            print("PMIx_Commit FAILED WITH ERROR",
                  myclient.error_string(rc))
            # cleanly finalize
            myclient.finalize()
            exit(1)
        print("Get value returned: ", get_val)

    # test a fence that should return not_supported because
    # we pass a required attribute that the server is known
    # not to support
    procs = []
    info = [{'key': 'ARBIT', 'flags': PMIX_INFO_REQD,
             'value':10, 'val_type':PMIX_INT}]
    rc = myclient.fence(procs, info)
    if PMIX_SUCCESS == rc:
        print("PMIx_Fence SUCCEEDED BUT SHOULD HAVE FAILED")
        # cleanly finalize
        myclient.finalize()
        exit(1)

    # Publish something
    info = [{'key': 'ARBITRARY', 'value':10, 'val_type':PMIX_INT}]
    rc = myclient.publish(info)
    if PMIX_SUCCESS != rc:
        print("PMIx_Publish FAILED WITH ERROR",
              myclient.error_string(rc))
        # cleanly finalize
        myclient.finalize()
        exit(1)

    # finalize
    info = []
    myclient.finalize(info)
    print("Client finalize complete")

# Python main program entry point
if __name__ == '__main__':
    main()
\end{codepar}
\pyspecificend


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Python Server}

The following example contains a minimum-level server host program that instantiates and initializes the PMIxServer class. The program illustrates passing several server module functions to the bindings and includes code to setup and spawn a simple client application, waiting until the spawned client terminates before finalizing and exiting itself. Note that the example has been formatted to fit the document layout.

\pyspecificstart
\begin{codepar}
from pmix import *
import signal, time
import os
import select
import subprocess

def clientconnected(proc:tuple is not None):
    print("CLIENT CONNECTED", proc)
    return PMIX_OPERATION_SUCCEEDED

def clientfinalized(proc:tuple is not None):
    print("CLIENT FINALIZED", proc)
    return PMIX_OPERATION_SUCCEEDED

def clientfence(procs:list, directives:list, data:bytearray):
    # check directives
    if directives is not None:
        for d in directives:
            # these are each an info dict
            if "pmix" not in d['key']:
                # we do not support such directives - see if
                # it is required
                try:
                    if d['flags'] & PMIX_INFO_REQD:
                        # return an error
                        return PMIX_ERR_NOT_SUPPORTED
                except:
                    #it can be ignored
                    pass
    return PMIX_OPERATION_SUCCEEDED

def main():
    try:
        myserver = PMIxServer()
    except:
        print("FAILED TO CREATE SERVER")
        exit(1)
    print("Testing server version ", myserver.get_version())

    args = [{'key':PMIX_SERVER_SCHEDULER,
             'value':'T', 'val_type':PMIX_BOOL}]
    map = {'clientconnected': clientconnected,
           'clientfinalized': clientfinalized,
           'fencenb': clientfence}
    my_result = myserver.init(args, map)

    # get our environment as a base
    env = os.environ.copy()

    # register an nspace for the client app
    (rc, regex) = myserver.generate_regex("test000,test001,test002")
    (rc, ppn) = myserver.generate_ppn("0")
    kvals = [{'key':PMIX_NODE_MAP,
              'value':regex, 'val_type':PMIX_STRING},
             {'key':PMIX_PROC_MAP,
              'value':ppn, 'val_type':PMIX_STRING},
             {'key':PMIX_UNIV_SIZE,
              'value':1, 'val_type':PMIX_UINT32},
             {'key':PMIX_JOB_SIZE,
              'value':1, 'val_type':PMIX_UINT32}]
    rc = foo.register_nspace("testnspace", 1, kvals)
    print("RegNspace ", rc)

    # register a client
    uid = os.getuid()
    gid = os.getgid()
    rc = myserver.register_client({'nspace':"testnspace", 'rank':0},
                                  uid, gid)
    print("RegClient ", rc)
    # setup the fork
    rc = myserver.setup_fork({'nspace':"testnspace", 'rank':0}, env)
    print("SetupFrk", rc)

    # setup the client argv
    args = ["./client.py"]
    # open a subprocess with stdout and stderr
    # as distinct pipes so we can capture their
    # output as the process runs
    p = subprocess.Popen(args, env=env,
        stdout=subprocess.PIPE, stderr=subprocess.PIPE)
    # define storage to catch the output
    stdout = []
    stderr = []
    # loop until the pipes close
    while True:
        reads = [p.stdout.fileno(), p.stderr.fileno()]
        ret = select.select(reads, [], [])

        stdout_done = True
        stderr_done = True

        for fd in ret[0]:
            # if the data
            if fd == p.stdout.fileno():
                read = p.stdout.readline()
                if read:
                    read = read.decode('utf-8').rstrip()
                    print('stdout: ' + read)
                    stdout_done = False
            elif fd == p.stderr.fileno():
                read = p.stderr.readline()
                if read:
                    read = read.decode('utf-8').rstrip()
                    print('stderr: ' + read)
                    stderr_done = False

        if stdout_done and stderr_done:
            break
    print("FINALIZING")
    myserver.finalize()


if __name__ == '__main__':
    main()
\end{codepar}
\pyspecificend

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