Sync the Standard to OpenPMIx

Signed-off-by: Ralph Castain <[email protected]>
(cherry picked from commit 9e1e5fe)

Chap_API_Reserved_Keys.tex

@@ -175,10 +175,18 @@ \subsection{Session realm attributes}
 Regular expression of nodes currently hosting processes in the specified realm - see \ref{cptr:api_server:noderegex} for an explanation of its generation. Defaults to the \refterm{job} realm.
 }
 %
+\declareAttributeNEW{PMIX_NODE_MAP_RAW}{"pmix.nmap.raw"}{char*}{
+Comma-delimited list of nodes containing procs within the specified realm. Defaults to the \refterm{job} realm.
+}
+%
 \declareAttribute{PMIX_PROC_MAP}{"pmix.pmap"}{char*}{
 Regular expression describing processes on each node in the specified realm - see \ref{cptr:api_server:ppnregex} for an explanation of its generation. Defaults to the \refterm{job} realm.
 }
 %
+\declareAttributeNEW{PMIX_PROC_MAP_RAW}{"pmix.pmap.raw"}{char*}{
+Semi-colon delimited list of strings, each string containing a comma-delimited list of ranks on the corresponding node within the specified realm. Defaults to the \refterm{job} realm.
+}
+%
 \declareAttribute{PMIX_ANL_MAP}{"pmix.anlmap"}{char*}{
 Process map equivalent to \refattr{PMIX_PROC_MAP} expressed in Argonne National Laboratory's PMI-1/PMI-2 notation. Defaults to the \refterm{job} realm.
 }

Chap_API_Struct.tex

@@ -428,6 +428,30 @@ \subsection{Rank Structure}
 \end{constantdesc}
 
 
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsubsection{Rank support macros}
+
+The following macros are provided for convenience when working with \ac{PMIx} ranks.
+
+\littleheader{Check rank macro}
+\declaremacro{PMIX_CHECK_RANK}
+
+Check two ranks for equality, taking into account wildcard values
+
+\versionMarker{4.0}
+\cspecificstart
+\begin{codepar}
+PMIX_CHECK_RANK(a, b)
+\end{codepar}
+\cspecificend
+
+\begin{arglist}
+\argin{a}{Rank to be checked (\refstruct{pmix_rank_t})}
+\argin{b}{Rank to be checked (\refstruct{pmix_rank_t})}
+\end{arglist}
+
+Returns \code{true} if the ranks are equal, or at least one of the ranks is \refconst{PMIX_RANK_WILDCARD}
+
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 \subsection{Process Structure}
 \declarestruct{pmix_proc_t}

Chap_API_Sync_Access.tex

@@ -246,7 +246,7 @@ \section{\code{PMIx_Get}}
 \begin{itemize}
     \item In the absence of any directive, the returned \refstruct{pmix_value_t} shall be an allocated memory object. The caller is responsible for releasing the object when done.
     \item If \refattr{PMIX_GET_POINTER_VALUES} is given, then the function shall return a pointer to a \refstruct{pmix_value_t} in the \ac{PMIx} library's memory that contains the requested information.
-    \item If \refattr{PMIX_GET_STATIC_VALUES} is given, then the function shall return the information in the provided \refstruct{pmix_value_t} pointer. In this case, the caller must provide storage for the structure and pass the pointer to that storage in the \refarg{val} parameter.
+    \item If \refattr{PMIX_GET_STATIC_VALUES} is given, then the function shall return the information in the provided \refstruct{pmix_value_t} pointer. In this case, the caller must provide storage for the structure and pass the pointer to that storage in the \refarg{val} parameter. If the implementation cannot return a static value, then the call to \refapi{PMIx_Get} must return the \refconst{PMIX_ERR_NOT_SUPPORTED} status.
 \end{itemize}
 
 This is a blocking operation - the caller will block until the retrieval rules of Chapters \ref{chap:api_rsvd_keys} or \ref{chap:nrkeys} are met.

Chap_API_Tools.tex

@@ -450,15 +450,12 @@ \subsection{Tool spawn-related attributes}
 \subsection{Tool rendezvous-related events}
 \label{api:tools:attributes:spawnconst}
 
-These constants refer to events relating to rendezvous of a tool and launcher during spawn of the \ac{IL}. The events serve as a form of event-driven "handshake" between the two processes, thereby allowing the tool to provide directives to the \ac{IL} prior to the \ac{IL} launching any processes.
+The following constants refer to events relating to rendezvous of a tool and launcher during spawn of the \ac{IL}.
 
 \begin{constantdesc}
 %
-\declareconstitemNEW{PMIX_LAUNCH_DIRECTIVE}
-When a launcher wishes to capture directives sent to it by a \ac{PMIx}-enabled tool, it shall register to receive this event. The specified callback function will be invoked when the event is received from the tool, thereby allowing the launcher to harvest the directives for its purposes.
-%
 \declareconstitemNEW{PMIX_LAUNCHER_READY}
-When an application launcher (e.g., \emph{mpiexec}) is ready to receive directives from a \ac{PMIx}-enabled tool, it shall generate this event to signal the tool to send the directives. Directives are conveyed to the launcher via the tool generating the \refconst{PMIX_LAUNCH_DIRECTIVE} event - see \refapi{PMIx_Notify_event} for details.
+An application launcher (e.g., \emph{mpiexec}) shall generate this event to signal a tool that started it that the launcher is ready to receive directives/commands (e.g., \refapi{PMIx_Spawn}). This is only used when the initiator is able to parse the command line itself, or the launcher is started as a persistent \ac{DVM}.
 %
 \end{constantdesc}
 

Chap_Revisions.tex

@@ -618,7 +618,6 @@ \subsection{Added Constants}
 %
 \littleheader{Tool constants}
 %
-\refconst{PMIX_LAUNCH_DIRECTIVE} \\
 \refconst{PMIX_LAUNCHER_READY} \\
 \refconst{PMIX_ERR_IOF_FAILURE} \\
 \refconst{PMIX_ERR_IOF_COMPLETE} \\
@@ -766,6 +765,8 @@ \subsection{Added Attributes}
 \pasteAttributeItem{PMIX_HOSTNAME_KEEP_FQDN}
 \pasteAttributeItem{PMIX_CPUSET_BITMAP}
 \pasteAttributeItem{PMIX_EXTERNAL_PROGRESS}
+\pasteAttributeItem{PMIX_NODE_MAP_RAW}
+\pasteAttributeItem{PMIX_PROC_MAP_RAW}
 %
 %
 \littleheader{Tool attributes}

bin/check-openpmix.py

@@ -135,6 +135,7 @@ def check_missing_openpmix(std_all_refs, openpmix_all_refs,
     std_consts = {}
     std_structs = {}
     std_apis = {}
+    std_envars = {}
     std_all_refs = {}
     std_deprecated = []
     std_removed = []
@@ -151,22 +152,27 @@ def check_missing_openpmix(std_all_refs, openpmix_all_refs,
     #
     parser = argparse.ArgumentParser(description="PMIx Standard / OpenPMIx Cross Check")
     parser.add_argument("-v", "--verbose", help="Verbose output", action="store_true")
+    parser.add_argument("-b", "--branch", help="OpenPMIx branch to be checked", nargs='?')
 
     parser.parse_args()
     args = parser.parse_args()
 
-
     #
     # Verify that we have the necessary files in the current working directory
     # * pmix-standard.aux
     # * check-openpmix
     #
     if os.path.exists("check-openpmix") is False:
         print("Warning: Missing OpenPMIx checkout. Trying to clone now")
-        os.system("git clone https://github.com/openpmix/openpmix.git check-openpmix")
+        if args.branch:
+            cmd = "git clone --single-branch -b " + args.branch + " https://github.com/openpmix/openpmix.git check-openpmix"
+            os.system(cmd)
         print("")
     else:
         os.system("cd check-openpmix ; git pull")
+        if args.branch:
+            cmd = "git checkout " + args.branch
+            os.system(cmd)
 
     if os.path.exists("pmix-standard.aux") is False or os.path.exists("check-openpmix") is False:
         print("Error: Cannot find the .aux files or OpenPMIx checkout necessary for processing in the current directory.")
@@ -181,8 +187,9 @@ def check_missing_openpmix(std_all_refs, openpmix_all_refs,
     # structs    - grep "newlabel{struct" pmix-standard.aux
     # macros     - grep "newlabel{macro" pmix-standard.aux
     # apis       - grep "newlabel{api" pmix-standard.aux
+    # envars     - grep "newlabel{envar" pmix-standard.aux
     # --------------------------------------------------
-    all_ref_strs = ["attr", "const", "struct", "macro", "apifn"]
+    all_ref_strs = ["attr", "const", "struct", "macro", "apifn", "envar"]
     for ref_str in all_ref_strs:
         if args.verbose is True:
             print "-"*50
@@ -221,6 +228,8 @@ def check_missing_openpmix(std_all_refs, openpmix_all_refs,
                 std_macros[m.group(1)] = -1
             elif ref_str == "apifn":
                 std_apis[m.group(1)] = -1
+            elif ref_str == "envar":
+                std_envars[m.group(1)] = -1
             else:
                 print("Error: Failed to classify the attribute: "+m.group(1))
                 sys.exit(1)
@@ -248,12 +257,16 @@ def check_missing_openpmix(std_all_refs, openpmix_all_refs,
         for val in std_removed:
             print("Std Removed      : " + val)
         print "-"*50
+        for val in std_envars:
+            print("Std Envar    : " + val)
+        print "-"*50
 
     print("Number of Standard attributes  : " + str(len(std_attributes)))
     print("Number of Standard consts      : " + str(len(std_consts)))
     print("Number of Standard structs     : " + str(len(std_structs)))
     print("Number of Standard macros      : " + str(len(std_macros)))
     print("Number of Standard apis        : " + str(len(std_apis)))
+    print("Number of Standard envars      : " + str(len(std_envars)))
     print("Total Number of Standard items : " + str(len(std_all_refs)))
     print("Number of Deprecated items     : " + str(len(std_deprecated)))
     print("Number of Removed items        : " + str(len(std_removed)))

pmix-standard.tex

@@ -137,6 +137,7 @@
 \acrodef{CUDA}{Compute Unified Device Architecture}
 \acrodef{HCA}{Host Channel Adapter}
 \acrodef{IP}{Internet Protocol}
+\acrodef{DVM}{Distributed Virtual Machine}
 
 %%%%%%%%%%%%%%%%%%%