diff --git a/Chap_API_Job_Mgmt.tex b/Chap_API_Job_Mgmt.tex index 3aae945..374cf9a 100644 --- a/Chap_API_Job_Mgmt.tex +++ b/Chap_API_Job_Mgmt.tex @@ -887,25 +887,34 @@ \subsection{\code{PMIx_Log}} \returnsimple \reqattrstart -If the \ac{PMIx} library does not itself perform this operation, then it is required to pass any attributes provided by the client to the host environment for processing. In addition, it must include the following attributes in the passed \refarg{info} array: +If the \ac{PMIx} library does not itself perform this operation, then it is required to pass any attributes provided by the client to the host environment for processing. In addition, it must include the following attributes in the passed \refarg{directives} array: \pasteAttributeItem{PMIX_USERID} \pasteAttributeItem{PMIX_GRPID} -Host environments or \ac{PMIx} libraries that implement support for this operation are required to support the following attributes: +Host environments or \ac{PMIx} libraries that implement support for this operation are required to support the following attributes when provided as part of the \refarg{data} array: \pasteAttributeItem{PMIX_LOG_STDERR} \pasteAttributeItem{PMIX_LOG_STDOUT} \pasteAttributeItem{PMIX_LOG_SYSLOG} -\pasteAttributeItem{PMIX_LOG_LOCAL_SYSLOG} -\pasteAttributeItem{PMIX_LOG_GLOBAL_SYSLOG} + +Similarly, the following attributes must be supported when provided as part of the \refarg{directives} array: + \pasteAttributeItem{PMIX_LOG_SYSLOG_PRI} \pasteAttributeItem{PMIX_LOG_ONCE} \reqattrend \optattrstart -The following attributes are optional for host environments or \ac{PMIx} libraries that support this operation: +The following attributes are optional for host environments or \ac{PMIx} libraries that support this operation when provided as part of the \refarg{data} array: + +\pasteAttributeItem{PMIX_LOG_EMAIL} +\pasteAttributeItem{PMIX_LOG_JOB_RECORD} +\pasteAttributeItem{PMIX_LOG_GLOBAL_DATASTORE} +\pasteAttributeItem{PMIX_LOG_LOCAL_SYSLOG} +\pasteAttributeItem{PMIX_LOG_GLOBAL_SYSLOG} + +Similarly, the following attributes are optional when provided as part of the \refarg{directives} array: \pasteAttributeItem{PMIX_LOG_SOURCE} \pasteAttributeItem{PMIX_LOG_TIMESTAMP} @@ -913,22 +922,24 @@ \subsection{\code{PMIx_Log}} \pasteAttributeItem{PMIX_LOG_TAG_OUTPUT} \pasteAttributeItem{PMIX_LOG_TIMESTAMP_OUTPUT} \pasteAttributeItem{PMIX_LOG_XML_OUTPUT} -\pasteAttributeItem{PMIX_LOG_EMAIL} -\pasteAttributeItem{PMIX_LOG_EMAIL_ADDR} -\pasteAttributeItem{PMIX_LOG_EMAIL_SENDER_ADDR} -\pasteAttributeItem{PMIX_LOG_EMAIL_SERVER} -\pasteAttributeItem{PMIX_LOG_EMAIL_SRVR_PORT} -\pasteAttributeItem{PMIX_LOG_EMAIL_SUBJECT} -\pasteAttributeItem{PMIX_LOG_EMAIL_MSG} -\pasteAttributeItem{PMIX_LOG_JOB_RECORD} -\pasteAttributeItem{PMIX_LOG_GLOBAL_DATASTORE} + \optattrend %%%% \descr -Log data subject to the services offered by the host environment. The data to be logged is provided in the \refarg{data} array. The (optional) \refarg{directives} can be used to direct the choice of logging channel. +Log data subject to the services offered by the host environment. The \refarg{data} array is used to specify the information that is to be logged, while the \refarg{directives} array is used to control formatting and other output options. For example, a user can: + +\begin{itemize} +\item log a message to \code{stderr} by including \refattr{PMIX_LOG_STDERR} in the \refarg{data} array, with the message itself provided as a string value in that \refstruct{pmix_info_t} element. They can also have that message time-stamped by including the \refattr{PMIX_LOG_TIMESTAMP} attribute in the \refarg{directives} array. +\item send an email to one or more recipients by including \refattr{PMIX_LOG_EMAIL} in the \refarg{data} array, with the \refstruct{pmix_data_array_t} value containing the message, recipient, and any required server information. Note that any \refarg{directives} (e.g., \refattr{PMIX_LOG_GENERATE_TIMESTAMP}) will be applied to the email request. +\item log a message to the syslog on the system console by including \refattr{PMIX_LOG_GLOBAL_SYSLOG} in the \refarg{data} array, with the message itself provided as a string value in that \refstruct{pmix_info_t} element. The syslog priority could be set with \refattr{PMIX_LOG_SYSLOG_PRI} in the \refarg{directives} array. +\end{itemize} + +Note that it is possible to log multiple messages to different channels using a single call to \refapi{PMIx_Log}. For instance, the above examples could be combined into a single call to \refapi{PMIx_Log}. In this case, only directives that are applicable to a channel will be used in outputting to that channel. For this example, a directive such as \refattr{PMIX_LOG_TIMESTAMP} would cause all three messages to be time-stamped, but a \refattr{PMIX_LOG_SYSLOG_PRI} directive would only be applied to the syslog channel. + +Multiple instances of the same attribute can be included in the \refarg{data} array - e.g., to send different emails to various recipients. \adviceuserstart It is strongly recommended that the \refapi{PMIx_Log} API not be used by applications for streaming data as it is not a ``performant'' transport and can perturb the application since it involves the local \ac{PMIx} server and host \ac{SMS} daemon. Note that a return of \refconst{PMIX_SUCCESS} only denotes that the data was successfully handed to the appropriate system call (for local channels) or the host environment and does not indicate receipt at the final destination. @@ -974,25 +985,34 @@ \subsection{\code{PMIx_Log_nb}} \returnend \reqattrstart -If the \ac{PMIx} library does not itself perform this operation, then it is required to pass any attributes provided by the client to the host environment for processing. In addition, it must include the following attributes in the passed \refarg{info} array: +If the \ac{PMIx} library does not itself perform this operation, then it is required to pass any attributes provided by the client to the host environment for processing. In addition, it must include the following attributes in the passed \refarg{directives} array: \pasteAttributeItem{PMIX_USERID} \pasteAttributeItem{PMIX_GRPID} -Host environments or \ac{PMIx} libraries that implement support for this operation are required to support the following attributes: +Host environments or \ac{PMIx} libraries that implement support for this operation are required to support the following attributes when provided as part of the \refarg{data} array: \pasteAttributeItem{PMIX_LOG_STDERR} \pasteAttributeItem{PMIX_LOG_STDOUT} \pasteAttributeItem{PMIX_LOG_SYSLOG} -\pasteAttributeItem{PMIX_LOG_LOCAL_SYSLOG} -\pasteAttributeItem{PMIX_LOG_GLOBAL_SYSLOG} + +Similarly, the following attributes must be supported when provided as part of the \refarg{directives} array: + \pasteAttributeItem{PMIX_LOG_SYSLOG_PRI} \pasteAttributeItem{PMIX_LOG_ONCE} \reqattrend \optattrstart -The following attributes are optional for host environments or \ac{PMIx} libraries that support this operation: +The following attributes are optional for host environments or \ac{PMIx} libraries that support this operation when provided as part of the \refarg{data} array: + +\pasteAttributeItem{PMIX_LOG_EMAIL} +\pasteAttributeItem{PMIX_LOG_JOB_RECORD} +\pasteAttributeItem{PMIX_LOG_GLOBAL_DATASTORE} +\pasteAttributeItem{PMIX_LOG_LOCAL_SYSLOG} +\pasteAttributeItem{PMIX_LOG_GLOBAL_SYSLOG} + +Similarly, the following attributes are optional when provided as part of the \refarg{directives} array: \pasteAttributeItem{PMIX_LOG_SOURCE} \pasteAttributeItem{PMIX_LOG_TIMESTAMP} @@ -1000,23 +1020,14 @@ \subsection{\code{PMIx_Log_nb}} \pasteAttributeItem{PMIX_LOG_TAG_OUTPUT} \pasteAttributeItem{PMIX_LOG_TIMESTAMP_OUTPUT} \pasteAttributeItem{PMIX_LOG_XML_OUTPUT} -\pasteAttributeItem{PMIX_LOG_EMAIL} -\pasteAttributeItem{PMIX_LOG_EMAIL_ADDR} -\pasteAttributeItem{PMIX_LOG_EMAIL_SENDER_ADDR} -\pasteAttributeItem{PMIX_LOG_EMAIL_SERVER} -\pasteAttributeItem{PMIX_LOG_EMAIL_SRVR_PORT} -\pasteAttributeItem{PMIX_LOG_EMAIL_SUBJECT} -\pasteAttributeItem{PMIX_LOG_EMAIL_MSG} -\pasteAttributeItem{PMIX_LOG_JOB_RECORD} -\pasteAttributeItem{PMIX_LOG_GLOBAL_DATASTORE} + \optattrend %%%% \descr -Log data subject to the services offered by the host environment. The data to be logged is provided in the \refarg{data} array. The (optional) \refarg{directives} can be used to direct the choice of logging channel. -The callback function will be executed when the log operation has been completed. The \refarg{data} and \refarg{directives} arrays must be maintained until the callback is provided. +Log data subject to the services offered by the host environment. See the description in \refapi{PMIx_Log} for details on use of the \refarg{data} and \refarg{directives} arrays. \adviceuserstart It is strongly recommended that the \refapi{PMIx_Log_nb} API not be used by applications for streaming data as it is not a ``performant'' transport and can perturb the application since it involves the local \ac{PMIx} server and host \ac{SMS} daemon. Note that a return of \refconst{PMIX_SUCCESS} only denotes that the data was successfully handed to the appropriate system call (for local channels) or the host environment and does not indicate receipt at the final destination. @@ -1085,12 +1096,14 @@ \subsection{Log attributes} Only log this once with whichever channel can first support it, taking the channels in priority order. } % -\declareAttribute{PMIX_LOG_MSG}{"pmix.log.msg"}{pmix_byte_object_t}{ -Message blob to be sent somewhere. -} -% \declareAttribute{PMIX_LOG_EMAIL}{"pmix.log.email"}{pmix_data_array_t}{ -Log via email based on \refstruct{pmix_info_t} containing directives. +Log via email based on \refstruct{pmix_info_t} containing directives. The array must contain at least one of +the \refattr{PMIX_LOG_BLOB} or \refattr{PMIX_LOG_MSG} attributes containing the body of the +message. In addition, it must contain at least the \refattr{PMIX_LOG_EMAIL_ADDR} and \refattr{PMIX_LOG_EMAIL_SUBJECT} +attributes identifying the intended recipients and the subject for the message. The array can optionally include +the server information (\refattr{PMIX_LOG_EMAIL_SERVER} and \refattr{PMIX_LOG_EMAIL_SRVR_PORT}) if required by the +local system, and a return email address for the sender (\refattr{PMIX_LOG_EMAIL_SENDER_ADDR}. No specific ordering +of these directives is required. } % \declareAttribute{PMIX_LOG_EMAIL_ADDR}{"pmix.log.emaddr"}{char*}{ @@ -1105,8 +1118,12 @@ \subsection{Log attributes} Subject line for email. } % -\declareAttribute{PMIX_LOG_EMAIL_MSG}{"pmix.log.emmsg"}{char*}{ -Message to be included in email. +\declareAttribute{PMIX_LOG_MSG}{"pmix.log.msg"}{char*}{ +Message to be included in a log operation. +} +% +\declareAttributeProvisional{PMIX_LOG_BLOB}{"pmix.log.blob"}{pmix_byte_object_t}{ +Message blob (e.g., PDF attachment) to be included in a log operation. } % \declareAttribute{PMIX_LOG_EMAIL_SERVER}{"pmix.log.esrvr"}{char*}{ @@ -1117,12 +1134,17 @@ \subsection{Log attributes} Port the email server is listening to. } % -\declareAttribute{PMIX_LOG_GLOBAL_DATASTORE}{"pmix.log.gstore"}{bool}{ -Store the log data in a global data store (e.g., database). +\declareAttributeProvisional{PMIX_LOG_GLOBAL_DATASTORE}{"pmix.log.gstore"}{pmix_data_array_t}{ +Store the log data in a global data store (e.g., database). Directs the host environment to +store the provided message in a data store available +to the host. The associated array must contain at least one of +the \refattr{PMIX_LOG_BLOB} or \refattr{PMIX_LOG_MSG} attributes containing the data to be +stored. } % -\declareAttribute{PMIX_LOG_JOB_RECORD}{"pmix.log.jrec"}{bool}{ -Log the provided information to the host environment's job record. +\declareAttributeProvisional{PMIX_LOG_JOB_RECORD}{"pmix.log.jrec"}{char*}{ +Log the provided message to the host environment's job record. An error must be returned if the host +does not support this service. } %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% diff --git a/Chap_API_Server.tex b/Chap_API_Server.tex index 0b15e3e..e57e200 100644 --- a/Chap_API_Server.tex +++ b/Chap_API_Server.tex @@ -2024,7 +2024,7 @@ \subsection{\code{pmix_server_module_t} Module} pmix_server_notify_event_fn_t notify_event; pmix_server_query_fn_t query; pmix_server_tool_connection_fn_t tool_connected; // DEPRECATED - pmix_server_log_fn_t log; + pmix_server_log_fn_t log; // DEPRECATED pmix_server_alloc_fn_t allocate; pmix_server_job_control_fn_t job_control; pmix_server_monitor_fn_t monitor; @@ -2038,6 +2038,7 @@ \subsection{\code{pmix_server_module_t} Module} pmix_server_fabric_fn_t fabric; pmix_server_client_connected2_fn_t client_connected2; pmix_server_tool_connection2_fn_t tool_connected2; + pmix_server_log2_fn_t log2; \} pmix_server_module_t; \end{codepar} \cspecificend @@ -3361,6 +3362,62 @@ \subsection{\code{pmix_server_tool_connection2_fn_t}} the connection is refused, the \ac{PMIx} server library must terminate the connection attempt. +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{\code{pmix_server_tool_connection_fn_t}} +\declareapi{pmix_server_tool_connection_fn_t} + +%%%% +\summary + +Register that a tool has connected to the server. + +%%%% +\format + +\copySignature{pmix_server_tool_connection_fn_t}{2.0}{ +typedef pmix_status_t (*pmix_server_tool_connection_fn_t)( \\ +\hspace*{29\sigspace}pmix_info_t info[], size_t ninfo, \\ +\hspace*{29\sigspace}pmix_tool_connection_cbfunc_t cbfunc, \\ +\hspace*{29\sigspace}void *cbdata); +} + +\begin{arglist} +\argin{info}{Array of \refstruct{pmix_info_t} structures (array of handles)} +\argin{ninfo}{Number of elements in the \refarg{info} array (integer)} +\argin{cbfunc}{Callback function \refapi{pmix_tool_connection_cbfunc_t} (function reference)} +\argin{cbdata}{Data to be passed to the callback function (memory reference)} +\end{arglist} + +\reqattrstart +\ac{PMIx} libraries are required to pass the following attributes in the \refarg{info} array: + +\pasteAttributeItem{PMIX_USERID} +\pasteAttributeItem{PMIX_GRPID} +\pasteAttributeItemBegin{PMIX_TOOL_NSPACE}This must be included only if the tool already has an assigned namespace. +\pasteAttributeItemEnd{} +\pasteAttributeItemBegin{PMIX_TOOL_RANK}This must be included only if the tool already has an assigned rank. +\pasteAttributeItemEnd{} +\pasteAttributeItem{PMIX_CREDENTIAL} + +\reqattrend + + +\optattrstart +The following attributes are optional for host environments that support this operation: + +\pasteAttributeItem{PMIX_FWD_STDOUT} +\pasteAttributeItem{PMIX_FWD_STDERR} +\pasteAttributeItem{PMIX_FWD_STDIN} +\pasteAttributeItem{PMIX_VERSION_INFO} + +\optattrend + +%%%% +\descr + +This function module entry has been \textbf{DEPRECATED} in favor of \refapi{pmix_server_tool_connection2_fn_t} + + %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Tool connection attributes} @@ -3415,63 +3472,93 @@ \subsubsection{PMIx Tool Connection Callback Function} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{\code{pmix_server_tool_connection_fn_t}} -\declareapi{pmix_server_tool_connection_fn_t} +\versionMarkerProvisional{6.0} +\subsection{\code{pmix_server_log2_fn_t}} +\declareapiProvisional{pmix_server_log2_fn_t} %%%% \summary -Register that a tool has connected to the server. +Log data on behalf of a client. %%%% \format -\copySignature{pmix_server_tool_connection_fn_t}{2.0}{ -typedef pmix_status_t (*pmix_server_tool_connection_fn_t)( \\ -\hspace*{29\sigspace}pmix_info_t info[], size_t ninfo, \\ -\hspace*{29\sigspace}pmix_tool_connection_cbfunc_t cbfunc, \\ -\hspace*{29\sigspace}void *cbdata); +\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{info}{Array of \refstruct{pmix_info_t} structures (array of handles)} -\argin{ninfo}{Number of elements in the \refarg{info} array (integer)} -\argin{cbfunc}{Callback function \refapi{pmix_tool_connection_cbfunc_t} (function reference)} +\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}. + \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 the following attributes in the \refarg{info} array: +If the \ac{PMIx} library calls this server module function, then it is required to pass any attributes provided by the client to the host environment for processing. In addition, it must include the following attributes in the passed \refarg{directives} array: \pasteAttributeItem{PMIX_USERID} \pasteAttributeItem{PMIX_GRPID} -\pasteAttributeItemBegin{PMIX_TOOL_NSPACE}This must be included only if the tool already has an assigned namespace. -\pasteAttributeItemEnd{} -\pasteAttributeItemBegin{PMIX_TOOL_RANK}This must be included only if the tool already has an assigned rank. -\pasteAttributeItemEnd{} -\pasteAttributeItem{PMIX_CREDENTIAL} -\reqattrend +Host environments that implement support for this operation are required to support the following attributes when provided as part of the \refarg{data} array: + +\pasteAttributeItem{PMIX_LOG_STDERR} +\pasteAttributeItem{PMIX_LOG_STDOUT} +\pasteAttributeItem{PMIX_LOG_SYSLOG} + +Similarly, the following attributes must be supported when provided as part of the \refarg{directives} array: +\pasteAttributeItem{PMIX_LOG_SYSLOG_PRI} +\pasteAttributeItem{PMIX_LOG_ONCE} + +\reqattrend \optattrstart -The following attributes are optional for host environments that support this operation: +The following attributes are optional for host environments that support this operation when provided as part of the \refarg{data} array: -\pasteAttributeItem{PMIX_FWD_STDOUT} -\pasteAttributeItem{PMIX_FWD_STDERR} -\pasteAttributeItem{PMIX_FWD_STDIN} -\pasteAttributeItem{PMIX_VERSION_INFO} +\pasteAttributeItem{PMIX_LOG_EMAIL} +\pasteAttributeItem{PMIX_LOG_JOB_RECORD} +\pasteAttributeItem{PMIX_LOG_GLOBAL_DATASTORE} +\pasteAttributeItem{PMIX_LOG_LOCAL_SYSLOG} +\pasteAttributeItem{PMIX_LOG_GLOBAL_SYSLOG} + +Similarly, the following attributes are optional when provided as part of the \refarg{directives} array: + +\pasteAttributeItem{PMIX_LOG_SOURCE} +\pasteAttributeItem{PMIX_LOG_TIMESTAMP} +\pasteAttributeItem{PMIX_LOG_GENERATE_TIMESTAMP} +\pasteAttributeItem{PMIX_LOG_TAG_OUTPUT} +\pasteAttributeItem{PMIX_LOG_TIMESTAMP_OUTPUT} +\pasteAttributeItem{PMIX_LOG_XML_OUTPUT} \optattrend %%%% \descr -This function module entry has been \textbf{DEPRECATED} in favor of \refapi{pmix_server_tool_connection2_fn_t} +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. See the description in \refapi{PMIx_Log} for further information on expected behavior. + %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{\code{pmix_server_log_fn_t}} -\declareapi{pmix_server_log_fn_t} +\declareapiDEPNODISP{pmix_server_log_fn_t} %%%% \summary @@ -3500,37 +3587,10 @@ \subsection{\code{pmix_server_log_fn_t}} \end{arglist} -\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. +Log data on behalf of a client. This function module entry has been \textbf{DEPRECATED} in favor of \refapi{pmix_server_log2_fn_t}. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%