diff --git a/Chap_API_Event.tex b/Chap_API_Event.tex index faeded9..db45f1b 100644 --- a/Chap_API_Event.tex +++ b/Chap_API_Event.tex @@ -43,8 +43,8 @@ \section{Notification and Management} % \end{itemize} -Users can specify the callback order of a handler within its category at the time of registration. -Users can specify that a given handler be executed before or after another target handler should both handlers appear in the event chain (the ordering is ignored if the other handler isn't included). +Users can specify the callback order of a handler within its category at the time of registration. +Users can specify that a given handler be executed before or after another target handler should both handlers appear in the event chain (the ordering is ignored if the other handler isn't included). The ordering is dictated by providing the event handler name of the target. The name must have been assigned when the target handler was registered. Note that ordering does not imply immediate relationships. For example, multiple handlers registered to be serviced after event handler \textit{A} will all be executed after \textit{A}, but are not guaranteed to be executed in any particular order amongst themselves. @@ -115,7 +115,7 @@ \subsection{\code{PMIx_Register_event_handler}} \end{itemize} \returnend -The callback function must not be executed prior to returning from the \ac{API}, and no events corresponding to this registration may be delivered prior to the completion of the registration callback function (\refarg{cbfunc}). +No events corresponding to this registration may be delivered prior to the completion of the registration callback function (\refarg{cbfunc}). \reqattrstart The following attributes are required to be supported by all \ac{PMIx} libraries: @@ -507,7 +507,7 @@ \subsection{\code{PMIx_Notify_event}} %%%% \descr -Report an event for notification via any registered event handler. This function can be called by any \ac{PMIx} process, including application processes, \ac{PMIx} servers, and \ac{SMS} elements. +Report an event for notification via any registered event handler. This function can be called by any \ac{PMIx} process, including application processes, \ac{PMIx} servers, and \ac{SMS} elements. The \ac{PMIx} server calls this \ac{API} to report events it detected itself so that the host \ac{SMS} daemon can distribute and handle them, and to pass events given to it by its host down to any attached client processes for processing. Examples might include notification of the failure of another process, detection of an impending node failure due to rising temperatures, or an intent to preempt the application. Events may be locally generated or come from anywhere in the system. @@ -578,7 +578,7 @@ \subsubsection{Completion Callback Function Status Codes} \begin{constantdesc} % \declareconstitemvalue{PMIX_EVENT_ACTION_COMPLETE}{-334} -Event handler: Action complete. +Event handler: Action complete. \end{constantdesc} % diff --git a/Chap_API_Query.tex b/Chap_API_Query.tex index c5f76be..469f66a 100644 --- a/Chap_API_Query.tex +++ b/Chap_API_Query.tex @@ -6,18 +6,18 @@ \chapter{Query Operations} This chapter presents mechanisms for generalized queries that access information about the host environment and the system in general. -The chapter presents the concept of a query followed by a detailed explanation +The chapter presents the concept of a query followed by a detailed explanation of the query \acp{API} provided. The chapter compares the use of these \acp{API} with \refapi{PMIx_Get}. The chapter concludes with detailed information about how to use the query interface to access information about what \ac{PMIx} \acp{API} an implementation supports as well as what attributes each supported \ac{API} supports. \section{PMIx_Query_info} As the level of interaction between applications and the host \ac{SMS} grows, so too does the need for the application to query the \ac{SMS} regarding its capabilities and state information. \ac{PMIx} provides a generalized query interface for this purpose, along with a set of standardized attribute keys to support a range of requests. This includes requests to determine the status of scheduling queues and active allocations, the scope of \ac{API} and attribute support offered by the \ac{SMS}, namespaces of active jobs, location and information about a job's processes, and information regarding available resources. -An example use-case for the \refapi{PMIx_Query_info_nb} \ac{API} is to ensure clean job completion. Time-shared systems frequently impose maximum run times when assigning jobs to resource allocations. To shut down gracefully (e.g., to write a checkpoint before termination) it is necessary for an application to periodically query the resource manager for the time remaining in its allocation. This is especially true on systems for which allocation times may be shortened or lengthened from the original time limit. Many resource managers provide \acp{API} to dynamically obtain this information, but each \ac{API} is specific to the resource manager. -\ac{PMIx} supports this use-case by defining an attribute key (\refattr{PMIX_TIME_REMAINING}) that can be used with the \refapi{PMIx_Query_info_nb} interface to obtain the number of seconds remaining in the current job allocation. +An example use-case for the \refapi{PMIx_Query_info_nb} \ac{API} is to ensure clean job completion. Time-shared systems frequently impose maximum run times when assigning jobs to resource allocations. To shut down gracefully (e.g., to write a checkpoint before termination) it is necessary for an application to periodically query the resource manager for the time remaining in its allocation. This is especially true on systems for which allocation times may be shortened or lengthened from the original time limit. Many resource managers provide \acp{API} to dynamically obtain this information, but each \ac{API} is specific to the resource manager. +\ac{PMIx} supports this use-case by defining an attribute key (\refattr{PMIX_TIME_REMAINING}) that can be used with the \refapi{PMIx_Query_info_nb} interface to obtain the number of seconds remaining in the current job allocation. -\ac{PMIx} sometimes provides multiple methods by which an application can obtain information or services. For this example, -note that one could alternatively use the \refapi{PMIx_Register_event_handler} \ac{API} to register for an event indicating incipient job termination, and then use the \refapi{PMIx_Job_control_nb} \ac{API} to request that the host \ac{SMS} generate an event a specified amount of time prior to reaching the maximum run time. +\ac{PMIx} sometimes provides multiple methods by which an application can obtain information or services. For this example, +note that one could alternatively use the \refapi{PMIx_Register_event_handler} \ac{API} to register for an event indicating incipient job termination, and then use the \refapi{PMIx_Job_control_nb} \ac{API} to request that the host \ac{SMS} generate an event a specified amount of time prior to reaching the maximum run time. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{Query Structure} @@ -105,7 +105,7 @@ \subsection{\code{PMIx_Query_info}} \pasteAttributeItem{PMIX_HOST_ATTRIBUTES} \pasteAttributeItem{PMIX_TOOL_ATTRIBUTES} -Note that inclusion of both the \refattr{PMIX_PROCID} directive and either the \refattr{PMIX_NSPACE} or the \refattr{PMIX_RANK} attribute will return a \refconst{PMIX_ERR_BAD_PARAM} result, and that the inclusion of a process identifier must apply to all keys in that \refstruct{pmix_query_t}. Queries for information on multiple specific processes therefore requires submitting multiple \refstruct{pmix_query_t} structures, each referencing one process. Directives which are not applicable to a key are ignored. +Note that inclusion of both the \refattr{PMIX_PROCID} directive and either the \refattr{PMIX_NSPACE} or the \refattr{PMIX_RANK} attribute will return a \refconst{PMIX_ERR_BAD_PARAM} result, and that the inclusion of a process identifier must apply to all keys in that \refstruct{pmix_query_t}. Queries for information on multiple specific processes therefore requires submitting multiple \refstruct{pmix_query_t} structures, each referencing one process. Directives which are not applicable to a key are ignored. % Use of pmix_server_query_fn is covered in server interfaces chapter \reqattrend @@ -187,8 +187,7 @@ \subsection{\code{PMIx_Query_info_nb}} \end{arglist} A successful return indicates that the request has been accepted for processing. -The provided callback function will only be executed upon successful return of the operation. -Note that the library must not invoke the callback function prior to returning from the \ac{API}. +The provided callback function will only be executed upon successful completion of the operation. \returnsimple @@ -228,7 +227,7 @@ \subsection{\code{PMIx_Query_info_nb}} \pasteAttributeItem{PMIX_HOST_ATTRIBUTES} \pasteAttributeItem{PMIX_TOOL_ATTRIBUTES} -Note that inclusion of both the \refattr{PMIX_PROCID} directive and either the \refattr{PMIX_NSPACE} or the \refattr{PMIX_RANK} attribute will return a \refconst{PMIX_ERR_BAD_PARAM} result, and that the inclusion of a process identifier must apply to all keys in that \refstruct{pmix_query_t}. Queries for information on multiple specific processes therefore requires submitting multiple \refstruct{pmix_query_t} structures, each referencing one process. Directives which are not applicable to a key are ignored. +Note that inclusion of both the \refattr{PMIX_PROCID} directive and either the \refattr{PMIX_NSPACE} or the \refattr{PMIX_RANK} attribute will return a \refconst{PMIX_ERR_BAD_PARAM} result, and that the inclusion of a process identifier must apply to all keys in that \refstruct{pmix_query_t}. Queries for information on multiple specific processes therefore requires submitting multiple \refstruct{pmix_query_t} structures, each referencing one process. Directives which are not applicable to a key are ignored. % Use of pmix_server_query_fn is covered in server interfaces chapter \reqattrend @@ -267,7 +266,7 @@ \subsection{\code{PMIx_Query_info_nb}} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %% NOTE: This is not used anywhere. If this is supposed to be returned by -%% the query API's, it was never indicated. They currently return +%% the query API's, it was never indicated. They currently return %% PMIX_ERR_PARTIAL_SUCCESS %%\subsection{Query-specific constants} %%\label{api:struct:constants:query} @@ -384,7 +383,7 @@ \subsection{Query keys} \subsection{Query attributes} \label{api:struct:attributes:query} -Attributes used to direct behavior of the +Attributes used to direct behavior of the \refapi{PMIx_Query_info} and \refapi{PMIx_Query_info_nb} \acp{API}: \declareAttribute{PMIX_QUERY_RESULTS}{"pmix.qry.res"}{pmix_data_array_t}{ diff --git a/Chap_API_Server.tex b/Chap_API_Server.tex index 7248bd2..a0ba910 100644 --- a/Chap_API_Server.tex +++ b/Chap_API_Server.tex @@ -874,7 +874,7 @@ \subsection{\code{PMIx_server_deregister_nspace}} \descr Deregister the specified \refarg{nspace} and purge all objects relating to it, including any client information from that namespace. -This is intended to support persistent \ac{PMIx} servers by providing an opportunity for the host \ac{RM} to tell the \ac{PMIx} server library to release all memory for a completed job. Note that the library must not invoke the callback function prior to returning from the \ac{API}, and that a \code{NULL} \refarg{cbfunc} reference indicates that the function is to be executed as a blocking operation. +This is intended to support persistent \ac{PMIx} servers by providing an opportunity for the host \ac{RM} to tell the \ac{PMIx} server library to release all memory for a completed job. Note that a \code{NULL} \refarg{cbfunc} reference indicates that the function is to be executed as a blocking operation. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -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 @@ -1045,7 +1045,7 @@ \subsection{\code{PMIx_server_deregister_client}} \descr The \refapi{PMIx_server_deregister_nspace} \ac{API} will delete all client information for that namespace. The \ac{PMIx} server library will automatically perform that operation upon disconnect of all local clients. -This \ac{API} is therefore intended primarily for use in exception cases, but can be called in non-exception cases if desired. Note that the library must not invoke the callback function prior to returning from the \ac{API}. +This \ac{API} is therefore intended primarily for use in exception cases, but can be called in non-exception cases if desired. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -2048,7 +2048,7 @@ \subsection{\code{pmix_server_client_connected_fn_t}} 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_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 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} @@ -2091,7 +2091,7 @@ \subsection{\code{pmix_server_client_connected2_fn_t}} 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_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 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. The \ac{PMIx} server library is to immediately terminate the connection. \end{itemize} @@ -2144,7 +2144,7 @@ \subsection{\code{pmix_server_client_finalized_fn_t}} 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_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 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} @@ -2207,7 +2207,7 @@ \subsection{\code{pmix_server_abort_fn_t}} 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_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_PARAM_VALUE_NOT_SUPPORTED} indicating that the host environment supports this \ac{API}, but the request includes processes that the host environment cannot abort - e.g., if the request is to abort subsets of processes from a namespace, or processes outside of the caller's own namespace, and the host environment does not permit such operations. In this case, none of the specified processes will be terminated - 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 @@ -2259,7 +2259,7 @@ \subsection{\code{pmix_server_fencenb_fn_t}} 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_SUCCESS}, indicating that the request is being processed by the host environment - result will be returned in the provided \refarg{cbfunc}. \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} @@ -2389,7 +2389,7 @@ \subsection{\code{pmix_server_dmodex_req_fn_t}} 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_SUCCESS}, indicating that the request is being processed by the host environment - result will be returned in the provided \refarg{cbfunc}. \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} @@ -2464,7 +2464,7 @@ \subsection{\code{pmix_server_publish_fn_t}} 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_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 @@ -2543,7 +2543,7 @@ \subsection{\code{pmix_server_lookup_fn_t}} 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_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 @@ -2620,7 +2620,7 @@ \subsection{\code{pmix_server_unpublish_fn_t}} 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_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 @@ -2695,7 +2695,7 @@ \subsection{\code{pmix_server_spawn_fn_t}} 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_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 @@ -2818,7 +2818,7 @@ \subsection{\code{pmix_server_connect_fn_t}} 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_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 @@ -2885,7 +2885,7 @@ \subsection{\code{pmix_server_disconnect_fn_t}} 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_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 @@ -2954,7 +2954,7 @@ \subsection{\code{pmix_server_register_events_fn_t}} 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_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 @@ -3018,7 +3018,7 @@ \subsection{\code{pmix_server_deregister_events_fn_t}} 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_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 @@ -3076,7 +3076,7 @@ \subsection{\code{pmix_server_notify_event_fn_t}} 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_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 @@ -3200,7 +3200,7 @@ \subsection{\code{pmix_server_query_fn_t}} 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_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 @@ -3318,8 +3318,7 @@ \subsection{\code{pmix_server_tool_connection_fn_t}} Approval or rejection of the connection request shall be returned in the \refarg{status} parameter of the \refapi{pmix_tool_connection_cbfunc_t}. If the connection is refused, the \ac{PMIx} server library must terminate the -connection attempt. The host must not execute the callback function prior to -returning from the \ac{API}. +connection attempt. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Tool connection attributes} @@ -3435,7 +3434,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 is not intended for output of computational results, but rather for reporting status and error messages. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -3472,7 +3471,7 @@ \subsection{\code{pmix_server_alloc_fn_t}} 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_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 @@ -3565,7 +3564,7 @@ \subsection{\code{pmix_server_job_control_fn_t}} 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_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 @@ -3653,7 +3652,7 @@ \subsection{\code{pmix_server_monitor_fn_t}} 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_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 @@ -3940,7 +3939,7 @@ \subsection{\code{pmix_server_iof_fn_t}} 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 library must not invoke the callback function prior to returning from the \ac{API}. + \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 @@ -3974,7 +3973,7 @@ \subsection{\code{pmix_server_iof_fn_t}} %%%% \descr -Request the specified IO channels be forwarded from the given array of processes. An error shall be returned in the callback function if the requested service from any of the requested processes cannot be provided. +Request the specified IO channels be forwarded from the given array of processes. An error shall be returned (either directly or in the callback function) if the requested service from any of the requested processes cannot be provided. \adviceimplstart The forwarding of stdin is a \textit{push} process - processes cannot request that it be \textit{pulled} from some other source. Requests including the \refconst{PMIX_FWD_STDIN_CHANNEL} channel will return a \refconst{PMIX_ERR_NOT_SUPPORTED} error. @@ -4056,7 +4055,7 @@ \subsection{\code{pmix_server_stdin_fn_t}} 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 library must not invoke the callback function prior to returning from the \ac{API}. + \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 @@ -4113,7 +4112,7 @@ \subsection{\code{pmix_server_grp_fn_t}} 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 library must not invoke the callback function prior to returning from the \ac{API}. + \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 @@ -4201,7 +4200,7 @@ \subsection{\code{pmix_server_fabric_fn_t}} 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 library must not invoke the callback function prior to returning from the \ac{API}. + \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 diff --git a/pmix.sty b/pmix.sty index ee23bc3..e58499e 100644 --- a/pmix.sty +++ b/pmix.sty @@ -436,7 +436,7 @@ % \pasteAttributeItem Paste a copy of the Attribute declaration % \pasteAttributeItemBegin Paste a copy of the Attribute declaration % \pasteAttributeItemEnd with space to extend the description. -% +% % \refconst Reference a Constant % @@ -537,7 +537,7 @@ % \pasteAttributeItem Paste a copy of the Attribute declaration % \pasteAttributeItemBegin Paste a copy of the Attribute declaration % \pasteAttributeItemEnd with space to extend the description. -% +% % \refAttributeItem or \refattr Reference an Attribute % @@ -897,7 +897,7 @@ \newcommand{\returnstart}{Returns PMIX_SUCCESS or one of the following error codes when the condition described occurs:} \newcommand{\returnend}{If none of the above return codes are appropriate, then an implementation must return either a general \ac{PMIx} error code or an implementation defined error code as described in Section \ref{api:struct:errors}.} \newcommand{\returnsimple}{Returns \refconst{PMIX_SUCCESS} or a negative value indicating the error.} -\newcommand{\returnsimplenb}{A successful return indicates that the request is being processed and the result will be returned in the provided \refarg{cbfunc}. Note that the library must not invoke the callback function prior to returning from the \ac{API}. The callback function, \refarg{cbfunc}, is only called when \refconst{PMIX_SUCCESS} is returned.} +\newcommand{\returnsimplenb}{A successful return indicates that the request is being processed and the result will be returned in the provided \refarg{cbfunc}. The callback function, \refarg{cbfunc}, is only called when \refconst{PMIX_SUCCESS} is returned.} % Rationale \newcommand{\rationalestart}{\VSPb\ratline{-1}{dashed}{Rationale}{7em}\VSPa}