Add a directive indicating that a reqd attribute has been processed (#…

…322)

* Add a directive indicating that a reqd attribute has been processed

Each level (client, server, host) needs to know if some prior level has
already processed a required attribute so it can correctly deal with it.
Define an info directive for that purpose, and provide macros to set and
test for that directive.

Signed-off-by: Ralph Castain <[email protected]>
Co-authored-by: Josh Hursey <[email protected]>

Chap_API_Server.tex

@@ -2019,10 +2019,12 @@ \section{Server Function Pointers}
 
 \ac{PMIx} utilizes a "function-shipping" approach to support for implementing the server-side of the protocol. This method allows \acp{RM} to implement the server without being burdened with \ac{PMIx} internal details. When a request is received from the client, the corresponding server function will be called with the information.
 
-Any functions not supported by the \ac{RM} can be indicated by a \code{NULL} for the function pointer. \ac{PMIx} implementations are required to return a \refconst{PMIX_ERR_NOT_SUPPORTED} status to all calls to functions that require host environment support and are not backed by a corresponding server module entry.
+Any functions not supported by the \ac{RM} can be indicated by a \code{NULL} for the function pointer. \ac{PMIx} implementations are required to return a \refconst{PMIX_ERR_NOT_SUPPORTED} status to all calls to functions that require host environment support and are not backed by a corresponding server module entry. Host environments may, if they choose, include a function pointer for operations they have not yet implemented and simply return \refconst{PMIX_ERR_NOT_SUPPORTED}.
+
+Functions that accept directives (i.e., arrays of \refstruct{pmix_info_t} structures) must check any provided directives for those marked as \emph{required} via the \refconst{PMIX_INFO_REQD} flag. \ac{PMIx} client and server libraries are required to mark any such directives with the \refconst{PMIX_INFO_REQD_PROCESSED} flag should they have handled the request. Any required directive that has not been marked therefore becomes the responsibility of the host environment. If a required directive that hasn't been processed by a lower level cannot be supported by the host, then the \refconst{PMIX_ERR_NOT_SUPPORTED} error constant must be returned. If the directive can be processed by the host, then the host shall do so and mark the attribute with the \refconst{PMIX_INFO_REQD_PROCESSED} flag.
 
 The host \ac{RM} will provide the function pointers in a \refapi{pmix_server_module_t} structure passed to \refapi{PMIx_server_init}.
-That module structure and associated function references are defined in this section.
+The module structure and associated function references are defined in this section.
 
 \advicermstart
 For performance purposes, the host server is required to return as quickly as possible from all functions. Execution of

Chap_API_Struct.tex

@@ -1455,6 +1455,9 @@ \subsection{Info Type Directives}
 \declareconstitem{PMIX_INFO_REQD}
 The behavior defined in the \refstruct{pmix_info_t} array is required, and not optional. This is a bit-mask value.
 %
+\declareconstitemNEW{PMIX_INFO_REQD_PROCESSED}
+Mark that this required attribute has been processed. A required attribute can be handled at any level - the \ac{PMIx} client library might take care of it, or it may be resolved by the \ac{PMIx} server library, or it may pass up to the host environment for handling. If a level does not recognize or support the required attribute, it is required to pass it upwards to give the next level an opportunity to process it. Thus, the host environment (or the server library if the host does not support the given operation) must know if a lower level has handled the requirement so it can return a \refconst{PMIX_ERR_NOT_SUPPORTED} error status if the host itself cannot meet the request. Upon processing the request, the level must therefore mark the attribute with this directive to alert any subsequent levels that the requirement has been met.
+%
 \declareconstitem{PMIX_INFO_ARRAY_END}
 Mark that this \refstruct{pmix_info_t} struct is at the end of an array created by the \refmacro{PMIX_INFO_CREATE} macro. This is a bit-mask value.
 %
@@ -1548,6 +1551,44 @@ \subsubsection{Info Directive support macros}
 
 Test the \refconst{PMIX_INFO_REQD} flag in a \refstruct{pmix_info_t} structure, returning \code{true} if the flag is \textit{not} set.
 
+%%%%%%%%%%%
+\littleheader{Mark a required attribute as processed}
+\declaremacro{PMIX_INFO_PROCESSED}
+
+Mark that a required \refstruct{pmix_info_t} structure has been processed.
+
+\versionMarker{4.0}
+\cspecificstart
+\begin{codepar}
+PMIX_INFO_PROCESSED(info);
+\end{codepar}
+\cspecificend
+
+\begin{arglist}
+\argin{info}{Pointer to the \refstruct{pmix_info_t} (pointer to \refstruct{pmix_info_t})}
+\end{arglist}
+
+Set the \refconst{PMIX_INFO_REQD_PROCESSED} flag in a \refstruct{pmix_info_t} structure indicating that is has been processed.
+
+%%%%%%%%%%%
+\littleheader{Test if a required attribute has been processed}
+\declaremacro{PMIX_INFO_WAS_PROCESSED}
+
+Test that a required \refstruct{pmix_info_t} structure has been processed.
+
+\versionMarker{4.0}
+\cspecificstart
+\begin{codepar}
+PMIX_INFO_WAS_PROCESSED(info);
+\end{codepar}
+\cspecificend
+
+\begin{arglist}
+\argin{info}{Pointer to the \refstruct{pmix_info_t} (pointer to \refstruct{pmix_info_t})}
+\end{arglist}
+
+Test the \refconst{PMIX_INFO_REQD_PROCESSED} flag in a \refstruct{pmix_info_t} structure.
+
 %%%%%%%%%%%
 \littleheader{Test an info structure for \textit{end of array} directive}
 \declaremacro{PMIX_INFO_IS_END}

Chap_Revisions.tex

@@ -604,6 +604,10 @@ \subsection{Added Constants}
 \refconst{PMIX_DATA_TYPE_MAX} \\
 \refconst{PMIX_COMPRESSED_BYTE_OBJECT} \\
 
+%
+\littleheader{Info directives}
+\refconst{PMIX_INFO_REQD_PROCESSED} \\
+
 %
 \littleheader{Server constants}
 \refconst{PMIX_ERR_REPEAT_ATTR_REGISTRATION} \\
@@ -880,6 +884,8 @@ \subsection{Added Environmental Variables}
 \subsection{Added Macros}
 %
 \refmacro{PMIX_CHECK_RESERVED_KEY}
+\refmacro{PMIX_INFO_WAS_PROCESSED}
+\refmacro{PMIX_INFO_PROCESSED}
 \refmacro{PMIX_INFO_LIST_START}
 \refmacro{PMIX_INFO_LIST_ADD}
 \refmacro{PMIX_INFO_LIST_XFER}