From 39ca7fbb470c5304df8560ade061721ff9dbcd55 Mon Sep 17 00:00:00 2001 From: Ralph Castain Date: Wed, 28 Oct 2020 13:49:51 -0700 Subject: [PATCH 1/4] Minor cleanups and clarifications Add reserved prefixes for regular expressions and explain that such prefixes are required to be present. Expand on explanation of refresh cache behavior and required keys. Add new compressed byte object data type. Signed-off-by: Ralph Castain --- Chap_API_Server.tex | 22 +++++++++++++++++----- Chap_API_Struct.tex | 3 +++ Chap_API_Sync_Access.tex | 3 ++- Chap_Revisions.tex | 2 ++ 4 files changed, 24 insertions(+), 6 deletions(-) diff --git a/Chap_API_Server.tex b/Chap_API_Server.tex index 17171549..a9651afa 100644 --- a/Chap_API_Server.tex +++ b/Chap_API_Server.tex @@ -652,13 +652,21 @@ \subsubsection{Assembling the registration information} free(nodelist); /* pass the regex as the value to the PMIX_NODE_MAP key */ -PMIX_INFO_LOAD(&info, PMIX_NODE_MAP, regex, PMIX_STRING); +PMIX_INFO_LOAD(&info, PMIX_NODE_MAP, regex, PMIX_REGEX); /* release the regex */ free(regex); \end{codepar} \cspecificend -Changing the filter criteria allows the construction of node maps for any level of information. +Changing the filter criteria allows the construction of node maps for any level of information. The returned regular expression shall start with a string identifier of the method used to generate the expression. This is followed by a colon (':') delimiter and then the regular expression itself. The following identifiers are reserved by the Standard: + +\begin{itemize} + \item \emph{raw} - indicates that the expression is simply the comma-delimited input string (no processing was performed) + \item \emph{native} - a \ac{PMIx}-unique regular expression generator and parser + \item \emph{compress} - a compressed format based on the zlib compression package +\end{itemize} + +Note that the regular expression itself is not required to be a printable string nor to obey typical string constraints (e.g., include a \code{NULL} terminator byte). \label{cptr:api_server:ppnregex}A similar method is used to construct the map of processes on each node from the namespace being registered. This may be done for each information level of interest (e.g., to identify the process map for the entire \refterm{job} or for each \refterm{application} in the job) by changing the search criteria. An example is shown below for the case of creating the process map for a \refterm{job}: @@ -709,7 +717,7 @@ \subsubsection{Assembling the registration information} free(ppn); /* pass the regex as the value to the PMIX_PROC_MAP key */ -PMIX_INFO_LOAD(&info, PMIX_PROC_MAP, regex, PMIX_STRING); +PMIX_INFO_LOAD(&info, PMIX_PROC_MAP, regex, PMIX_REGEX); /* release the regex */ free(regex); \end{codepar} @@ -1252,6 +1260,8 @@ \subsection{\code{PMIx_server_setup_application}} \pasteAttributeItem{PMIX_ALLOC_BANDWIDTH} \pasteAttributeItem{PMIX_ALLOC_FABRIC_QOS} +\pasteAttributeItemBegin{PMIX_SESSION_INFO}In this context, indicates that the information provided in the \refattr{PMIX_NODE_MAP} is for the entire session and not just the indicated namespace. Thus, subsequent calls to this \ac{API} may omit node-level information - e.g., the library may not need to include information on the devices on each node in a subsequent call. +\pasteAttributeItemEnd The following optional attributes may be provided by the host environment to identify the programming model (as specified by the user) being executed within the application. The \ac{PMIx} server library may utilize this information to harvest/forward model-specific environmental variables, record the programming model associated with the application, etc. @@ -1619,6 +1629,8 @@ \subsection{\code{PMIx_server_setup_local_support}} \advicermstart Host environments are required to execute this operation prior to starting any local application processes from the specified namespace if information was obtained from a call to \refapi{PMIx_server_setup_application}. + +Host environments must register the \refarg{nspace} using \refapi{PMIx_server_register_nspace} prior to calling this \ac{API} to ensure that all namespace-related information required to support this function is available to the library. This eliminates the need to include any of the registration information in the \refarg{info} array passed to this \ac{API}. \advicermend %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -2515,8 +2527,8 @@ \subsection{\code{pmix_server_dmodex_req_fn_t}} \subsubsection{Dmodex attributes} % -\declareAttribute{PMIX_REQUIRED_KEY}{"pmix.req.key"}{char*}{ -Key the user needs prior to responding from a dmodex request. +\declareAttributeNEW{PMIX_REQUIRED_KEY}{"pmix.req.key"}{char*}{ +Identifies a key that must be included in the requested information. If the specified key is not already available, then the \ac{PMIx} servers are required to delay response to the dmodex request until either the key becomes available or the request times out. } diff --git a/Chap_API_Struct.tex b/Chap_API_Struct.tex index 87b4ad8c..ab5671c3 100644 --- a/Chap_API_Struct.tex +++ b/Chap_API_Struct.tex @@ -2090,6 +2090,9 @@ \section{Generalized Data Types Used for Packing/Unpacking} \declareconstitem{PMIX_COMPRESSED_STRING} String compressed with zlib (\code{char*}). % +\declareconstitemNEW{PMIX_COMPRESSED_BYTE_OBJECT} +Byte object whose bytes have been compressed with zlib (\code{pmix_byte_object_t}). +% \declareconstitem{PMIX_ALLOC_DIRECTIVE} Allocation directive (\refstruct{pmix_alloc_directive_t}). % diff --git a/Chap_API_Sync_Access.tex b/Chap_API_Sync_Access.tex index 42dc7798..8b3784dd 100644 --- a/Chap_API_Sync_Access.tex +++ b/Chap_API_Sync_Access.tex @@ -227,6 +227,7 @@ \section{\code{PMIx_Get}} \pasteAttributeItem{PMIX_NODE_INFO} \pasteAttributeItem{PMIX_GET_STATIC_VALUES} \pasteAttributeItem{PMIX_GET_POINTER_VALUES} +\pasteAttributeItem{PMIX_GET_REFRESH_CACHE} \reqattrend @@ -358,7 +359,7 @@ \subsection{Retrieval attributes} } % \declareAttributeNEW{PMIX_GET_REFRESH_CACHE}{"pmix.get.refresh"}{bool}{ -When retrieving data for a remote process, refresh the existing local data cache for the process in case new values have been put and committed by the process since the last refresh. +When retrieving data for a remote process, refresh the existing local data cache for the process in case new values have been put and committed by the process since the last refresh. Local process information is assumed to be automatically updated upon posting by the process. A \code{NULL} key will cause all values associated with the process to be refreshed - otherwise, only the indicated key will be updated. A process rank of \refconst{PMIX_RANK_WILDCARD} can be used to update job-related information in dynamic environments. The user is responsible for subsequently updating refreshed values they may have cached in their own local memory. } % \declareAttribute{PMIX_DATA_SCOPE}{"pmix.scope"}{pmix_scope_t}{ diff --git a/Chap_Revisions.tex b/Chap_Revisions.tex index f70bf9dc..b39cb334 100644 --- a/Chap_Revisions.tex +++ b/Chap_Revisions.tex @@ -432,6 +432,7 @@ \subsection{Added Constants} \refconst{PMIX_DEVTYPE} \\ \refconst{PMIX_LOCTYPE} \\ \refconst{PMIX_DATA_TYPE_MAX} \\ +\refconst{PMIX_COMPRESSED_BYTE_OBJECT} \\ % \littleheader{Server constants} @@ -568,6 +569,7 @@ \subsection{Added Attributes} \pasteAttributeItem{PMIX_MIN_VALUE} \pasteAttributeItem{PMIX_ENUM_VALUE} \pasteAttributeItem{PMIX_HOMOGENEOUS_SYSTEM} +\pasteAttributeItem{PMIX_REQUIRED_KEY} % % \littleheader{Job-Mgmt attributes} From e929ed8a1210919a5c5e32420fc185af300b5fab Mon Sep 17 00:00:00 2001 From: Ralph Castain Date: Thu, 29 Oct 2020 09:15:57 -0700 Subject: [PATCH 2/4] Cleanup the regex description language Per the provided comments Signed-off-by: Ralph Castain --- Chap_API_Server.tex | 26 ++++++++------------------ 1 file changed, 8 insertions(+), 18 deletions(-) diff --git a/Chap_API_Server.tex b/Chap_API_Server.tex index a9651afa..d478c262 100644 --- a/Chap_API_Server.tex +++ b/Chap_API_Server.tex @@ -273,13 +273,15 @@ \subsection{\code{PMIx_generate_regex}} Given a comma-separated list of \refarg{input} values, generate a reduced size representation of the input that can be passed down to the \ac{PMIx} server library's \refapi{PMIx_server_register_nspace} \ac{API} for parsing. The order of the individual values in the \refarg{input} string is preserved across the operation. The caller is responsible for releasing the returned data. -The precise compressed representations will be implementation specific. However, all \ac{PMIx} implementations are required to include a \code{NULL}-terminated string in the output representation that can be printed for diagnostic purposes. +\label{regex:fmt}The precise compressed representations will be implementation specific. The regular expression itself is not required to be a printable string nor to obey typical string constraints (e.g., include a \code{NULL} terminator byte). However, all \ac{PMIx} implementations are required to include a colon-delimited \code{NULL}-terminated string at the beginning of the output representation that can be printed for diagnostic purposes and identifies the method used to generate the representation. The following identifiers are reserved by the Standard: -\advicermstart -The returned representation may be an arbitrary array of bytes as opposed to a valid \code{NULL}-terminated string. However, the method used to generate the representation shall be identified with a colon-delimited string at the beginning of the output. For example, an output starting with \code{"pmix:\textbackslash0"} might indicate that the representation is a \ac{PMIx}-defined regular expression represented as a \code{NULL}-terminated string following the \code{"pmix:\textbackslash0"} prefix. In contrast, an output starting with \code{"blob:\textbackslash0"} might indicate a compressed binary array follows the prefix. +\begin{itemize} + \item \code{"raw:\textbackslash0"} - indicates that the expression following the identifier is simply the comma-delimited input string (no processing was performed). + \item \code{"pmix:\textbackslash0"} - a \ac{PMIx}-unique regular expression represented as a \code{NULL}-terminated string following the identifier. + \item \code{"blob:\textbackslash0"} - a compressed binary array format based on the \emph{zlib} compression package, with the size encoded in the space immediately following the identifier. +\end{itemize} Communicating the resulting output should be done by first packing the returned expression using the \refapi{PMIx_Data_pack}, declaring the input to be of type \refconst{PMIX_REGEX}, and then obtaining the resulting blob to be communicated using the \refmacro{PMIX_DATA_BUFFER_UNLOAD} macro. The reciprocal method can be used on the remote end prior to passing the regex into \refapi{PMIx_server_register_nspace}. The pack/unpack routines will ensure proper handling of the data based on the regex prefix. -\advicermend %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -314,11 +316,7 @@ \subsection{\code{PMIx_generate_ppn}} The input shall consist of a semicolon-separated list of ranges representing the ranks of processes on each node of the job - e.g., \code{"1-4;2-5;8,10,11,12;6,7,9"}. Each field of the input must correspond to the node name provided at that position in the input to \refapi{PMIx_generate_regex}. Thus, in the example, ranks 1-4 would be located on the first node of the comma-separated list of names provided to \refapi{PMIx_generate_regex}, and ranks 2-5 would be on the second name in the list. -\advicermstart -The returned representation may be an arbitrary array of bytes as opposed to a valid \code{NULL}-terminated string. However, the method used to generate the representation shall be identified with a colon-delimited string at the beginning of the output. For example, an output starting with \code{"pmix:"} indicates that the representation is a \ac{PMIx}-defined regular expression represented as a \code{NULL}-terminated string. In contrast, an output starting with \code{"blob:\textbackslash0size=1234:"} is a compressed binary array. - -Communicating the resulting output should be done by first packing the returned expression using the \refapi{PMIx_Data_pack}, declaring the input to be of type \refconst{PMIX_REGEX}, and then obtaining the blob to be communicated using the \refmacro{PMIX_DATA_BUFFER_UNLOAD} macro. The pack/unpack routines will ensure proper handling of the data based on the regex prefix. -\advicermend +Rules governing the format of the returned regular expression are the same as those specified for \refapi{PMIx_generate_regex}, as detailed \hyperref[regex:fmt]{here}. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{\code{PMIx_server_register_nspace}} @@ -658,15 +656,7 @@ \subsubsection{Assembling the registration information} \end{codepar} \cspecificend -Changing the filter criteria allows the construction of node maps for any level of information. The returned regular expression shall start with a string identifier of the method used to generate the expression. This is followed by a colon (':') delimiter and then the regular expression itself. The following identifiers are reserved by the Standard: - -\begin{itemize} - \item \emph{raw} - indicates that the expression is simply the comma-delimited input string (no processing was performed) - \item \emph{native} - a \ac{PMIx}-unique regular expression generator and parser - \item \emph{compress} - a compressed format based on the zlib compression package -\end{itemize} - -Note that the regular expression itself is not required to be a printable string nor to obey typical string constraints (e.g., include a \code{NULL} terminator byte). +Changing the filter criteria allows the construction of node maps for any level of information. A description of the returned regular expression is provided \hyperref[regex:fmt]{here}. \label{cptr:api_server:ppnregex}A similar method is used to construct the map of processes on each node from the namespace being registered. This may be done for each information level of interest (e.g., to identify the process map for the entire \refterm{job} or for each \refterm{application} in the job) by changing the search criteria. An example is shown below for the case of creating the process map for a \refterm{job}: From cc2aa6d7a7351258006446c763a714ff1f1dd53a Mon Sep 17 00:00:00 2001 From: Ralph Castain Date: Thu, 29 Oct 2020 12:23:39 -0700 Subject: [PATCH 3/4] Update Chap_API_Server.tex Looks good to me. Signed-off-by: Ralph Castain Co-authored-by: Josh Hursey <4259120+jjhursey@users.noreply.github.com> --- Chap_API_Server.tex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Chap_API_Server.tex b/Chap_API_Server.tex index d478c262..9582b374 100644 --- a/Chap_API_Server.tex +++ b/Chap_API_Server.tex @@ -278,7 +278,7 @@ \subsection{\code{PMIx_generate_regex}} \begin{itemize} \item \code{"raw:\textbackslash0"} - indicates that the expression following the identifier is simply the comma-delimited input string (no processing was performed). \item \code{"pmix:\textbackslash0"} - a \ac{PMIx}-unique regular expression represented as a \code{NULL}-terminated string following the identifier. - \item \code{"blob:\textbackslash0"} - a compressed binary array format based on the \emph{zlib} compression package, with the size encoded in the space immediately following the identifier. + \item \code{"blob:\textbackslash0"} - a \ac{PMIx}-unique regular expression that is not represented as a \code{NULL}-terminated string following the identifier. Additional implementation-specific metadata may follow the identifier along with the data itself. For example, a compressed binary array format based on the \emph{zlib} compression package, with the size encoded in the space immediately following the identifier. \end{itemize} Communicating the resulting output should be done by first packing the returned expression using the \refapi{PMIx_Data_pack}, declaring the input to be of type \refconst{PMIX_REGEX}, and then obtaining the resulting blob to be communicated using the \refmacro{PMIX_DATA_BUFFER_UNLOAD} macro. The reciprocal method can be used on the remote end prior to passing the regex into \refapi{PMIx_server_register_nspace}. The pack/unpack routines will ensure proper handling of the data based on the regex prefix. From d560896d74e7a4e840d5c74a71674a3924f4583d Mon Sep 17 00:00:00 2001 From: Ralph Castain Date: Thu, 29 Oct 2020 12:24:01 -0700 Subject: [PATCH 4/4] Update Chap_API_Server.tex Signed-off-by: Ralph Castain Co-authored-by: Josh Hursey <4259120+jjhursey@users.noreply.github.com> --- Chap_API_Server.tex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Chap_API_Server.tex b/Chap_API_Server.tex index 9582b374..366b351e 100644 --- a/Chap_API_Server.tex +++ b/Chap_API_Server.tex @@ -273,7 +273,7 @@ \subsection{\code{PMIx_generate_regex}} Given a comma-separated list of \refarg{input} values, generate a reduced size representation of the input that can be passed down to the \ac{PMIx} server library's \refapi{PMIx_server_register_nspace} \ac{API} for parsing. The order of the individual values in the \refarg{input} string is preserved across the operation. The caller is responsible for releasing the returned data. -\label{regex:fmt}The precise compressed representations will be implementation specific. The regular expression itself is not required to be a printable string nor to obey typical string constraints (e.g., include a \code{NULL} terminator byte). However, all \ac{PMIx} implementations are required to include a colon-delimited \code{NULL}-terminated string at the beginning of the output representation that can be printed for diagnostic purposes and identifies the method used to generate the representation. The following identifiers are reserved by the Standard: +\label{regex:fmt}The precise compressed representations will be implementation specific. The regular expression itself is not required to be a printable string nor to obey typical string constraints (e.g., include a \code{NULL} terminator byte). However, all \ac{PMIx} implementations are required to include a colon-delimited \code{NULL}-terminated string at the beginning of the output representation that can be printed for diagnostic purposes and identifies the method used to generate the representation. The following identifiers are reserved by the \ac{PMIx} Standard: \begin{itemize} \item \code{"raw:\textbackslash0"} - indicates that the expression following the identifier is simply the comma-delimited input string (no processing was performed).