Updates to Python bindings and missed API

Replace the bitarray types in Python bindings with simple integer lists
for ease of use/translation. Cleanup some missing functions.

Add PMIX_EXTERNAL_PROGRESS attribute and PMIx_Progress API so that a
host can externally progress the PMIx library. This is less onerous than
requiring the host to also adopt libevent and provide an event base.
Deprecate the PMIX_EVENT_BASE attribute.

I had forgotten about the external progress promise until someone
pointed it out to me.

Signed-off-by: Ralph Castain <rhc@pmix.org>

App_Python.tex

@@ -74,9 +74,9 @@ \section{Datatype Definitions}
         \refstruct{pmix_proc_state_t} & PMIX_PROC_STATE & integer & value shall be limited to the \code{uint8_t} range \\ \hline
         \refstruct{pmix_proc_info_t} & 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} & 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}  & PMIX_INFO_DIRECTIVES & \pylabel{info directives}bitarray & 32-bit array \\ \hline
+        \refstruct{pmix_info_directives_t}  & PMIX_INFO_DIRECTIVES & \pylabel{info directives}list & list of integer values (defined in Section \ref{api:struct:infodirs}) \\ \hline
         \refstruct{pmix_alloc_directive_t} & PMIX_ALLOC_DIRECTIVE & \pylabel{allocdir}integer & value shall be limited to the \code{uint8_t} range \\ \hline
-        \refstruct{pmix_iof_channel_t} & PMIX_IOF_CHANNEL & \pylabel{channel}bitarray & 16-bit array \\ \hline
+        \refstruct{pmix_iof_channel_t} & PMIX_IOF_CHANNEL & \pylabel{channel}list & list of integer values (defined in Section \ref{api:tool:iofchannels}) \\ \hline
         \refstruct{pmix_envar_t} & 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} & 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} & 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
@@ -86,15 +86,15 @@ \section{Datatype Definitions}
         \refstruct{pmix_regattr_t} & 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} & PMIX_JOB_STATE & integer & value shall be limited to the \code{uint8_t} range \\ \hline
         \refstruct{pmix_link_state_t} & PMIX_LINK_STATE & integer & value shall be limited to the \code{uint8_t} range \\ \hline
-        \refstruct{pmix_cpuset_t} & 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 bitarray containing the cpuset \\ \hline
-        \refstruct{pmix_locality_t} & PMIX_LOCTYPE & \pylabel{locality}bitarray & 16-bit array containing the relative locality of the specified local process \\ \hline
+        \refstruct{pmix_cpuset_t} & 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} & 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} & 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} & 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} & 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} & 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} & PMIX_DEVTYPE & \pylabel{devtype}bitarray & 16-bit array \\ \hline
-        \refstruct{pmix_bind_envelope_t} & N/A & \pylabel{bindenv}integer & \\ \hline
+        \refstruct{pmix_device_type_t} & 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}
@@ -2335,7 +2335,7 @@ \subsection{Client.load_topology}
     \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 accessible by Python.
+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.
 
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@@ -2364,43 +2364,12 @@ \subsection{Client.get_relative_locality}
 
 \begin{itemize}
     \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
-    \item \refarg{locality} - \refpy{locality} bitarray containing the relative locality of the two processes (bitarray)
+    \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.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(cpusetstr:str)
-\end{codepar}
-\pyspecificend
-
-\begin{arglist}
-\argin{cpusetstr}{String of a cpuset (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{cpuset} - \refpy{cpuset} containing the source and bitmap of the cpuset (dict)
-\end{itemize}
-
-See \refapi{PMIx_Parse_cpuset_string} for details.
-
-
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 \subsection{Client.get_cpuset}
 \declareapibinding{PMIxClient.get_cpuset}{PMIx_Get_cpuset}{Python}
@@ -2450,7 +2419,7 @@ \subsection{Client.compute_distances}
 
 \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 (str)}
+\argin{info}{List of \refpy{info} dictionaries describing the devices whose distance is to be computed (list)}
 \end{arglist}
 
 
@@ -2461,7 +2430,7 @@ \subsection{Client.compute_distances}
     \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.
+See \refapi{PMIx_Compute_distances} for details. Note that distances can only be computed against the local topology.
 
 
 

Chap_API_Init.tex

@@ -125,7 +125,7 @@ \section{\code{PMIx_Init}}
 \pasteAttributeItemEnd{}
 \pasteAttributeItemBegin{PMIX_TCP_DISABLE_IPV6} If the library supports IPV6 connections, this attribute may be supported for disabling it.
 \pasteAttributeItemEnd{}
-\pasteAttributeItem{PMIX_EVENT_BASE}
+\pasteAttributeItem{PMIX_EXTERNAL_PROGRESS}
 \optattrend
 
 %%%%
@@ -316,4 +316,31 @@ \subsection{Finalize attributes}
 }
 
 
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\section{\code{PMIx_Progress}}
+\declareapi{PMIx_Progress}
+
+%%%%
+\summary
+
+Progress the \ac{PMIx} library.
+
+%%%%
+\format
+
+\versionMarker{4.0}
+\cspecificstart
+\begin{codepar}
+void
+PMIx_Progress(void)
+\end{codepar}
+\cspecificend
+
+
+%%%%
+\descr
+
+Progress the \ac{PMIx} library. Note that special care must be taken to avoid deadlocking in \ac{PMIx} callback functions and acp{API}.
+
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

Chap_API_Proc_Mgmt.tex

@@ -1225,6 +1225,7 @@ \subsubsection{Topology support macros}
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 \subsubsection{Relative locality of two processes}
 \declarestruct{pmix_locality_t}
+\label{api:proc:locality}
 
 \versionMarker{4.0}
 The \refstruct{pmix_locality_t} datatype is a \code{uint16_t} bitmask that
@@ -1358,6 +1359,7 @@ \subsection{\code{PMIx_Get_cpuset}}
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 \subsubsection{Binding envelope}
 \declarestruct{pmix_bind_envelope_t}
+\label{api:proc:bindenv}
 
 \versionMarker{4.0}
 The \refstruct{pmix_bind_envelope_t} data type
@@ -1511,6 +1513,7 @@ \subsection{Device Distance Callback Function}
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 \subsection{Device type}
 \declarestruct{pmix_device_type_t}
+\label{api:proc:devtype}
 
 The \refstruct{pmix_device_type_t} is a \code{uint64_t} bitmask for identifying the type(s) whose distances are being requested, or the type of a specific device being referenced (e.g., in a \refstruct{pmix_device_distance_t} object).
 

Chap_API_Server.tex

@@ -93,7 +93,7 @@ \subsection{\code{PMIx_server_init}}
 \pasteAttributeItemEnd{}
 \pasteAttributeItemBegin{PMIX_SERVER_REMOTE_CONNECTIONS} If the library supports connections from remote tools, this attribute may be supported for enabling or disabling it.
 \pasteAttributeItemEnd{}
-\pasteAttributeItem{PMIX_EVENT_BASE}
+\pasteAttributeItem{PMIX_EXTERNAL_PROGRESS}
 \pasteAttributeItem{PMIX_TOPOLOGY2}
 \pasteAttributeItemBegin{PMIX_SERVER_SHARE_TOPOLOGY}The \ac{PMIx} server will
 perform the necessary actions to scalably expose the description to the local
@@ -224,8 +224,9 @@ \subsection{Server Initialization Attributes}
 Server is supporting system scheduler and desires access to appropriate services.
 }
 %
-\declareAttribute{PMIX_EVENT_BASE}{"pmix.evbase"}{struct event_base *}{
-Pointer to libevent\footnote{\url{http://libevent.org/}} \code{event_base} to use in place of the internal progress thread.
+%
+\declareAttributeNEW{PMIX_EXTERNAL_PROGRESS}{"pmix.evext"}{bool}{
+The host shall progress the \ac{PMIx} library via calls to \refapi{PMIx_Progress}
 }
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

Chap_API_Struct.tex

@@ -1270,6 +1270,7 @@ \subsubsection{Info structure support macros}
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 \subsection{Info Type Directives}
 \declarestruct{pmix_info_directives_t}
+\label{api:struct:infodirs}
 
 \versionMarker{2.0}
 The \refstruct{pmix_info_directives_t} structure is a \code{uint32_t} type that defines the behavior of command directives via \refstruct{pmix_info_t} arrays.

Chap_API_Tools.tex

@@ -564,6 +564,7 @@ \subsection{Forwarding stdin}
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 \subsection{IO Forwarding Channels}
 \declarestruct{pmix_iof_channel_t}
+\label{api:tool:iofchannels}
 
 \versionMarker{3.0}
 The \refstruct{pmix_iof_channel_t} structure is a \code{uint16_t} type that defines a set of bit-mask flags for specifying IO forwarding channels. These can be bitwise OR'd together to reference multiple channels.
@@ -1116,7 +1117,7 @@ \subsection{\code{PMIx_tool_init}}
 \pasteAttributeItemEnd{}
 \pasteAttributeItemBegin{PMIX_TCP_DISABLE_IPV6} If the library supports IPV6 connections, this attribute may be supported for disabling it.
 \pasteAttributeItemEnd{}
-\pasteAttributeItem{PMIX_EVENT_BASE}
+\pasteAttributeItem{PMIX_EXTERNAL_PROGRESS}
 
 \optattrend
 

Chap_Revisions.tex

@@ -992,5 +992,9 @@ \subsection{Removed attributes}
 \declareAttributeDEP{PMIX_ARCH}{"pmix.arch"}{uint32_t}{
 Architecture flag.
 }
+%
+\declareAttributeDEP{PMIX_EVENT_BASE}{"pmix.evbase"}{struct event_base *}{
+Pointer to libevent\footnote{\url{http://libevent.org/}} \code{event_base} to use in place of the internal progress thread.
+}
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%