Merge pull request #320 from rhc54/cmr4/sync

Sync the Standard to OpenPMIx

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_Server.tex

@@ -998,7 +998,7 @@ \subsection{\code{PMIx_server_register_client}}
 \argin{uid}{user id (integer)}
 \argin{gid}{group id (integer)}
 \argin{server_object}{(memory reference)}
-\argin{cbfunc}{Callback function \refapi{pmix_op_cbfunc_t} (function reference)}
+\argin{cbfunc}{Callback function \refapi{pmix_op_cbfunc_t}. A \code{NULL} function reference indicates that the function is to be executed as a blocking operation (function reference)}
 \argin{cbdata}{Data to be passed to the callback function (memory reference)}
 \end{arglist}
 
@@ -1052,7 +1052,7 @@ \subsection{\code{PMIx_server_deregister_client}}
 
 \begin{arglist}
 \argin{proc}{\refstruct{pmix_proc_t} structure (handle)}
-\argin{cbfunc}{Callback function \refapi{pmix_op_cbfunc_t} (function reference)}
+\argin{cbfunc}{Callback function \refapi{pmix_op_cbfunc_t}. A \code{NULL} function reference indicates that the function is to be executed as a blocking operation (function reference)}
 \argin{cbdata}{Data to be passed to the callback function (memory reference)}
 \end{arglist}
 
@@ -1598,7 +1598,7 @@ \subsection{\code{PMIx_server_setup_local_support}}
 \argin{nspace}{Namespace (string)}
 \argin{info}{Array of info structures (array of handles)}
 \argin{ninfo}{Number of elements in the \refarg{info} array (\code{size_t})}
-\argin{cbfunc}{Callback function \refapi{pmix_op_cbfunc_t} (function reference)}
+\argin{cbfunc}{Callback function \refapi{pmix_op_cbfunc_t}. A \code{NULL} function reference indicates that the function is to be executed as a blocking operation (function reference)}
 \argin{cbdata}{Data to be passed to the callback function (memory reference)}
 \end{arglist}
 
@@ -1652,7 +1652,7 @@ \subsection{\code{PMIx_server_IOF_deliver}}
 \argin{bo}{Pointer to \refstruct{pmix_byte_object_t} containing the payload to be delivered (handle)}
 \argin{info}{Array of \refstruct{pmix_info_t} metadata describing the data (array of handles)}
 \argin{ninfo}{Number of elements in the \refarg{info} array (\code{size_t})}
-\argin{cbfunc}{Callback function \refapi{pmix_op_cbfunc_t} (function reference)}
+\argin{cbfunc}{Callback function \refapi{pmix_op_cbfunc_t}. A \code{NULL} function reference indicates that the function is to be executed as a blocking operation (function reference)}
 \argin{cbdata}{Data to be passed to the callback function (memory reference)}
 \end{arglist}
 
@@ -1740,7 +1740,7 @@ \subsection{\code{PMIx_server_deliver_inventory}}
 \argin{ninfo}{Number of elements in the \refarg{info} array (\code{size_t})}
 \argin{directives}{Array of \refstruct{pmix_info_t} directing the request (array of handles)}
 \argin{ndirs}{Number of elements in the \refarg{directives} array (\code{size_t})}
-\argin{cbfunc}{Callback function \refapi{pmix_op_cbfunc_t} (function reference)}
+\argin{cbfunc}{Callback function \refapi{pmix_op_cbfunc_t}. A \code{NULL} function reference indicates that the function is to be executed as a blocking operation (function reference)}
 \argin{cbdata}{Data to be passed to the callback function (memory reference)}
 \end{arglist}
 

Chap_API_Struct.tex

@@ -431,6 +431,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

@@ -513,15 +513,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

@@ -619,7 +619,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} \\
@@ -767,6 +766,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}

Makefile

@@ -2,6 +2,7 @@
 # For more information, see the master document, pmix-standard.tex.
 
 version=4.0
+OPENPMIX_BRANCH ?= "v4.0"
 default: pmix-standard.pdf
 
 CHAPTERS= \
@@ -88,9 +89,12 @@ check-decl: pmix-standard.pdf FORCECHECK
 	@echo "====> Checking for Multi-declared items"
 	@./bin/check-multi-declare.py
 
+# The default is defined near the top of the Makefile
+# To change the default at runtime you can manually set the envar:
+#   OPENPMIX_BRANCH=master make check-openpmix
 check-openpmix: pmix-standard.pdf FORCECHECK
 	@echo "====> Checking cross-reference with OpenPMIx"
-	@./bin/check-openpmix.py
+	@./bin/check-openpmix.py -b ${OPENPMIX_BRANCH}
 
 clean:
 	rm -f $(INTERMEDIATE_FILES) pmix-standard-*.pdf

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,37 @@ 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='?', default="master")
 
     parser.parse_args()
     args = parser.parse_args()
 
-
     #
     # Verify that we have the necessary files in the current working directory
     # * pmix-standard.aux
     # * check-openpmix
     #
+    print "-"*50
+    print "Checking: OpenPMIx checkout (branch: "+args.branch+")"
+    print "-"*50
     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")
-        print("")
+        cmd = "git clone --single-branch -b " + args.branch + " https://github.com/openpmix/openpmix.git check-openpmix"
+        rtn = os.system(cmd)
+        if rtn != 0:
+            print("Error: Failed to checkout the requested branch.")
+            print("       Command: " + cmd)
+            sys.exit(1)
     else:
-        os.system("cd check-openpmix ; git pull")
+        cmd = "cd check-openpmix ; git pull ; git checkout " + args.branch
+        rtn = os.system(cmd)
+        if rtn != 0:
+            print("Error: Failed to checkout the requested branch.")
+            print("       Command: " + cmd)
+            sys.exit(1)
+
+    print "-"*50
+    print("")
 
     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 +197,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 +238,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 +267,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}
 
 %%%%%%%%%%%%%%%%%%%