Replace the "log" server module fn with a "log2"

The current "log" server module function was defined with
a void return. This contrasts with most of the other module
functions which characteristically return a pmix_status_t,
thereby supporting a return status that indicates if the
function is not supported or has been atomically completed.

Add a replacement "log2" function that is identical in signature
except for returning a pmix_status_t instead of void. Deprecate
the current "log" function.

Signed-off-by: Ralph Castain <[email protected]>

Author: rhc54

Chap_API_Server.tex

@@ -955,7 +955,7 @@ \subsection{\code{PMIx_server_deregister_resources}}
 
 A \code{NULL} \refarg{cbfunc} reference indicates that the function is to be executed as a blocking operation.
 % TODO: If this is one of those functions that can be blocking or non-blocking, then
-% it needs a full return code explanation, not the returnsimple 
+% it needs a full return code explanation, not the returnsimple
 
 \advicermend
 
@@ -2009,6 +2009,7 @@ \subsection{\code{pmix_server_module_t} Module}
     pmix_server_grp_fn_t                group;
     pmix_server_fabric_fn_t             fabric;
     pmix_server_client_connected2_fn_t  client_connected2;
+    pmix_server_log2_fn_t               log2;
 \} pmix_server_module_t;
 \end{codepar}
 \cspecificend
@@ -3374,9 +3375,82 @@ \subsubsection{PMIx Tool Connection Callback Function}
 \advicermend
 
 
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\versionMarkerProvisional{5.1}
+\subsection{\code{pmix_server_log2_fn_t}}
+\declareapiProvisional{pmix_server_log2_fn_t}
+
+%%%%
+\summary
+
+Log data on behalf of a client.
+
+%%%%
+\format
+
+\copySignature{pmix_server_log2_fn_t}{5.1}{
+typedef pmix_status_t (*pmix_server_log2_fn_t)( \\
+\hspace*{20\sigspace}const pmix_proc_t *client, \\
+\hspace*{20\sigspace}const pmix_info_t data[], size_t ndata, \\
+\hspace*{20\sigspace}const pmix_info_t directives[], size_t ndirs, \\
+\hspace*{20\sigspace}pmix_op_cbfunc_t cbfunc, void *cbdata);
+}
+
+\begin{arglist}
+\argin{client}{\refstruct{pmix_proc_t} structure (handle)}
+\argin{data}{Array of info structures (array of handles)}
+\argin{ndata}{Number of elements in the \refarg{data} array (integer)}
+\argin{directives}{Array of info structures (array of handles)}
+\argin{ndirs}{Number of elements in the \refarg{directives} array (integer)}
+\argin{cbfunc}{Callback function \refapi{pmix_op_cbfunc_t} (function reference)}
+\argin{cbdata}{Data to be passed to the callback function (memory reference)}
+\end{arglist}
+
+Returns one of the following:
+
+\begin{itemize}
+    \item \refconst{PMIX_SUCCESS}, indicating that the request is being processed by the host environment - result will be returned in the provided \refarg{cbfunc}. Note that the host must not invoke the callback function prior to returning from the \ac{API}.
+    \item \refconst{PMIX_OPERATION_SUCCEEDED}, indicating that the request was immediately processed and returned \textit{success} - the \refarg{cbfunc} will not be called
+    \item \refconst{PMIX_ERR_NOT_SUPPORTED}, indicating that the host environment does not support the request, even though the function entry was provided in the server module - the \refarg{cbfunc} will not be called
+    \item a PMIx error constant indicating either an error in the input or that the request was immediately processed and failed - the \refarg{cbfunc} will not be called
+\end{itemize}
+
+\reqattrstart
+\ac{PMIx} libraries are required to pass any provided attributes to the host environment for processing. In addition, the following attributes are required to be included in the passed \refarg{info} array:
+
+\pasteAttributeItem{PMIX_USERID}
+\pasteAttributeItem{PMIX_GRPID}
+
+\divider
+
+Host environments that provide this module entry point are required to support the following attributes:
+
+\pasteAttributeItem{PMIX_LOG_STDERR}
+\pasteAttributeItem{PMIX_LOG_STDOUT}
+\pasteAttributeItem{PMIX_LOG_SYSLOG}
+
+\reqattrend
+
+\optattrstart
+The following attributes are optional for host environments that support this operation:
+
+\pasteAttributeItem{PMIX_LOG_MSG}
+\pasteAttributeItem{PMIX_LOG_EMAIL}
+\pasteAttributeItem{PMIX_LOG_EMAIL_ADDR}
+\pasteAttributeItem{PMIX_LOG_EMAIL_SUBJECT}
+\pasteAttributeItem{PMIX_LOG_EMAIL_MSG}
+
+\optattrend
+
+%%%%
+\descr
+
+Log data on behalf of a client. This function is not intended for output of computational results, but rather for reporting status and error messages. The host must not execute the callback function prior to returning from the \ac{API}.
+
+
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 \subsection{\code{pmix_server_log_fn_t}}
-\declareapi{pmix_server_log_fn_t}
+\declareapiDEPNODISP{pmix_server_log_fn_t}
 
 %%%%
 \summary
@@ -3435,7 +3509,7 @@ \subsection{\code{pmix_server_log_fn_t}}
 %%%%
 \descr
 
-Log data on behalf of a client. This function is not intended for output of computational results, but rather for reporting status and error messages. The host must not execute the callback function prior to returning from the \ac{API}.
+Log data on behalf of a client. This function module entry has been \textbf{DEPRECATED} in favor of \refapi{pmix_server_log2_fn_t}.
 
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%