Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 5 additions & 5 deletions Chap_API_Event.tex
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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}
%

Expand Down
21 changes: 10 additions & 11 deletions Chap_API_Query.tex
Original file line number Diff line number Diff line change
Expand Up @@ -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}
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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}
Expand Down Expand Up @@ -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}{
Expand Down
Loading