ckpt

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

Author: rhc54

Chap_API_Job_Mgmt.tex

@@ -712,8 +712,8 @@ \subsection{\code{PMIx_Process_monitor_nb}}
 }
 
 \begin{arglist}
-\argin{monitor}{info (handle)}
-\argin{error}{status (integer)}
+\argin{monitor}{Pointer to \restruct{pmix_info_t} specifying monitoring action (handle)}
+\argin{error}{\ac{PMIx} constant that to be used when generating an associated monitoring event (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_info_cbfunc_t} (function reference)}
@@ -731,22 +731,49 @@ \subsection{\code{PMIx_Process_monitor_nb}}
 \returnend
 
 \optattrstart
-The following attributes may be implemented by a \ac{PMIx} library or by the host environment. If supported by the \ac{PMIx} server library, then the library must not pass the supported attributes to the host environment. All attributes not directly supported by the server library must be passed to the host environment if it supports this operation, and the library is \textit{required} to add the \refAttributeItem{PMIX_USERID} and the \refAttributeItem{PMIX_GRPID} attributes of the requesting process:
+The following attributes may be implemented by a \ac{PMIx} library or by the host environment. If an attribute is supported by the \ac{PMIx} server library, then the library must not pass the supported attributes to the host environment unless the requested action involves other nodes. In addition, the library is \textit{required} to add the \refAttributeItem{PMIX_USERID} and the \refAttributeItem{PMIX_GRPID} attributes of the requesting process to the directives array when it passes actions to its host.
 
-\pasteAttributeItem{PMIX_MONITOR_ID}
-\pasteAttributeItem{PMIX_MONITOR_CANCEL}
-\pasteAttributeItem{PMIX_MONITOR_APP_CONTROL}
-\pasteAttributeItem{PMIX_MONITOR_HEARTBEAT}
-\pasteAttributeItem{PMIX_MONITOR_HEARTBEAT_TIME}
-\pasteAttributeItem{PMIX_MONITOR_HEARTBEAT_DROPS}
-\pasteAttributeItem{PMIX_MONITOR_FILE}
-\pasteAttributeItem{PMIX_MONITOR_FILE_SIZE}
-\pasteAttributeItem{PMIX_MONITOR_FILE_ACCESS}
-\pasteAttributeItem{PMIX_MONITOR_FILE_MODIFY}
-\pasteAttributeItem{PMIX_MONITOR_FILE_CHECK_TIME}
-\pasteAttributeItem{PMIX_MONITOR_FILE_DROPS}
-\pasteAttributeItem{PMIX_SEND_HEARTBEAT}
-\pasteAttributeItem{PMIX_MONITOR_RESOURCE_USAGE}
+The \refarg{monitor} argument may contain any of the following actions:
+
+\begin{itemize}
+    \item \pasteAttributeItem{PMIX_MONITOR_CANCEL}
+    \item \pasteAttributeItem{PMIX_MONITOR_HEARTBEAT}. The associated \refarg{directives} array may include any of the following:
+    \begin{itemize}
+        \item \pasteAttributeItem{PMIX_MONITOR_HEARTBEAT_TIME}
+        \item \pasteAttributeItem{PMIX_MONITOR_HEARTBEAT_DROPS}
+    \end{itemize}
+    \item \pasteAttributeItem{PMIX_SEND_HEARTBEAT}
+    \item \pasteAttributeItem{PMIX_MONITOR_FILE}. The associated \refarg{directives} array may include any of the following:
+    \begin{itemize}
+        \item \pasteAttributeItem{PMIX_MONITOR_FILE_SIZE}
+        \item \pasteAttributeItem{PMIX_MONITOR_FILE_ACCESS}
+        \item \pasteAttributeItem{PMIX_MONITOR_FILE_MODIFY}
+        \item \pasteAttributeItem{PMIX_MONITOR_FILE_CHECK_TIME}
+        \item \pasteAttributeItem{PMIX_MONITOR_FILE_DROPS}
+    \end{itemize}
+    \item \pasteAttributeItem{PMIX_MONITOR_PROC_RESOURCE_USAGE}. The associated \refarg{directives} array may include any of the following:
+    \begin{itemize}
+        \item \refattr{PMIX_MONITOR_RESOURCE_RATE}
+        \item \refattr{PMIX_MONITOR_TARGET_PROCS}
+        \item \refattr{PMIX_MONITOR_TARGET_PIDS}
+        \item \refattr{PMIX_MONITOR_TARGET_NODES}. All processes on the specified nodes are to be monitored.
+        \item \refattr{PMIX_MONITOR_TARGET_NODEIDS}. All processes on the specified nodes are to be monitored.
+    \end{itemize}
+    \item \pasteAttributeItem{PMIX_MONITOR_NODE_RESOURCE_USAGE}. The associated \refarg{directives} array may include any of the following:
+    \begin{itemize}
+        \item \refattr{PMIX_MONITOR_RESOURCE_RATE}
+        \item \refattr{PMIX_MONITOR_TARGET_NODES}
+        \item \refattr{PMIX_MONITOR_TARGET_NODEIDS}
+        \item \refattr{PMIX_MONITOR_TARGET_PROCS}. Monitor the nodes where the specified processes are located.
+    \end{itemize}
+\end{itemize}
+
+In addition to action-specific directives, the \refarg{directives} array may include:
+
+\begin{itemize}
+    \item \pasteAttributeItem{PMIX_MONITOR_ID}
+    \item \pasteAttributeItem{PMIX_MONITOR_APP_CONTROL}
+    \item \pasteAttributeItem{PMIX_RANGE}. Non-default range to be used when generating the associated event for this monitoring action.
 \optattrend
 
 %%%%
@@ -790,8 +817,99 @@ \subsection{Monitoring events}
 \declareconstitemvalue{PMIX_MONITOR_FILE_ALERT}{-110}
 File failed its monitoring detection criteria. The file that triggered this alert will be identified in the event.
 %
+\declareconstitemvalueProvisional{PMIX_MONITOR_RESUSAGE_UPDATE}{-112}
+Resource usage update - the report will be included in the event information.
+%
 \end{constantdesc}
 
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Monitoring Datatypes}
+
+The following datatype definitions have been created to support monitoring operations and information.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsubsection{Node PID Structure}
+\declarestructProvisional{pmix_node_pid_t}
+
+The \refstruct{pmix_node_pid_t} structure contains the hostname and pid of a process executing on that host.
+Since a pid is uniquely associated with a given host, this creates a conjugate pair.
+
+\copySignature{pmix_node_pid_t}{6.0}{
+typedef struct pmix_node_pid \{ \\
+\hspace*{4\sigspace}char *hostname; \\
+\hspace*{4\sigspace}pid_t pid; \\
+\} pmix_node_pid_t;
+}
+
+The \refarg{pid} field contains the \ac{pid_t} of the process, while the \refarg{hostname} is the name of the node where the process is executing.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsubsection{Node PID support functions}
+
+The following functions are provided for convenience when working with \refstruct{pmix_node_pid_t} structures.
+
+\littleheader{Initialize the node_pid structure}
+\declareapiProvisional{PMIx_Nodepid_construct}
+
+Initialize the \refstruct{pmix_node_pid_t} fields.
+
+\copySignature{PMIx_Nodepid_construct}{6.0}{
+void
+PMIx_Nodepid_construct(pmix_node_pid_t *p);
+}
+
+\begin{arglist}
+\argin{p}{Pointer to the structure to be initialized(pointer to \refstruct{pmix_node_pid_t})}
+\end{arglist}
+
+\littleheader{Destruct the node_pid structure}
+\declareapiProvisional{PMIx_Nodepid_destruct}
+
+Destruct the \refstruct{pmix_node_pid_t} fields.
+
+\copySignature{PMIx_Nodepid_destruct}{6.0}{
+void
+PMIx_Nodepid_destruct(pmix_node_pid_t *p);
+}
+
+\begin{arglist}
+\argin{p}{Pointer to the structure to be destructed (pointer to \refstruct{pmix_node_pid_t})}
+\end{arglist}
+
+\littleheader{Create an array of node_pid structures}
+\declareapiProvisional{PMIx_Nodepid_create}
+
+Allocate and initialize an array of \refstruct{pmix_node_pid_t} structures.
+
+\copySignature{PMIx_Nodepid_create}{6.0}{
+pmix_node_pid_t*
+PMIx_Nodepid_create(size_t n);
+}
+
+\begin{arglist}
+\argin{n}{Number of \refstruct{pmix_node_pid_t} structures to allocate}
+\end{arglist}
+
+Returns \refstruct{pmix_node_pid_t} pointer to the allocated array
+
+\littleheader{Release an array of node_pid structures}
+\declareapiProvisional{PMIx_Nodepid_free}
+
+Free all allocated memory in an array of \refstruct{pmix_node_pid_t} structures.
+
+\copySignature{PMIx_Nodepid_free}{6.0}{
+void
+PMIx_Nodepid_free(pmix_node_pid_t *p,
+\hspace*{4\sigspace}size_t n);
+}
+
+\begin{arglist}
+\argin{p}{Pointer to the array to be released (pointer to \refstruct{pmix_node_pid_t})}
+\argin{n}{Number of \refstruct{pmix_node_pid_t} structures in array}
+\end{arglist}
+
+
 %%%%%%%%%%%
 \subsection{Monitoring attributes}
 \label{api:struct:attributes:monitor}
@@ -828,19 +946,19 @@ \subsection{Monitoring attributes}
 }
 %
 \declareAttribute{PMIX_MONITOR_FILE}{"pmix.monitor.fmon"}{char*}{
-Register to monitor file for signs of life.
+Register to monitor file for signs of life - the value contains the filename to be monitored.
 }
 %
 \declareAttribute{PMIX_MONITOR_FILE_SIZE}{"pmix.monitor.fsize"}{bool}{
 Monitor size of given file is growing to determine if the application is running.
 }
 %
-\declareAttribute{PMIX_MONITOR_FILE_ACCESS}{"pmix.monitor.faccess"}{char*}{
-Monitor time since last access of given file to determine if the application is running.
+\declareAttribute{PMIX_MONITOR_FILE_ACCESS}{"pmix.monitor.faccess"}{bool}{
+Monitor time since last access to determine if the application is running.
 }
 %
-\declareAttribute{PMIX_MONITOR_FILE_MODIFY}{"pmix.monitor.fmod"}{char*}{
-Monitor time since last modified of given file to determine if the application is running.
+\declareAttribute{PMIX_MONITOR_FILE_MODIFY}{"pmix.monitor.fmod"}{bool}{
+Monitor time since last modified to determine if the application is running.
 }
 %
 \declareAttribute{PMIX_MONITOR_FILE_CHECK_TIME}{"pmix.monitor.ftime"}{uint32_t}{
@@ -851,31 +969,40 @@ \subsection{Monitoring attributes}
 Number of file checks that can be missed before generating the event.
 }
 %
+\declareAttributeProvisional{PMIX_MONITOR_TARGET_PROCS}{pmix.monitor.tgtproc}{pmix_data_array_t*}{
+Arrray of process IDs specifying the processes to be monitored. Can include a
+\refconst{PMIX_RANK_WILDCARD} to indicate that all processes
+from a given namespace are to be included. If omitted, then
+all processes in the session will be monitored. May be included
+multiple times to fully specify all processes to be included.
+%
+\declareAttributeProvisional{PMIX_MONITOR_TARGET_PIDS}{pmix.monitor.tgtpid}{pmix_data_array_t*}{
+Array of \refstruct{pmix_node_pid_t} structures to be monitored. Can include a
+structure containing a hostname with a pid value of \code{-1} to indicate all
+processes on that node are to be included. May be included
+multiple times to fully specify all processes to be included.
+%
+\declareAttributeProvisional{PMIX_MONITOR_TARGET_NODES}{pmix.monitor.tgtnode}{pmix_data_array_t*}{
+Array of host names to be monitored
+%
+\declareAttributeProvisional{PMIX_MONITOR_TARGET_NODEIDS}{pmix.monitor.tgtndids}{pmix_data_array_t*}{
+Array of node IDs (\code{uint32_t}) to be monitored
+%
 \declareAttributeProvisional{PMIX_MONITOR_RESOURCE_RATE}{pmix.monitor.resrate}{uint64_t}{
 Monitor resource usage every N seconds, where N is the value provided by the attribute.
 }
 %
-\declareAttributeProvisional{PMIX_MONITOR_RESOURCE_USAGE}{"pmix.monitor.resuse"}{pmix_data_array_t*}{
-Monitor the resources specified in the provided \refstruct{pmix_data_array_t}. Resource types may
+\declareAttributeProvisional{PMIX_MONITOR_PROC_RESOURCE_USAGE}{"pmix.monitor.presuse"}{pmix_data_array_t*}{
+Monitor the resources specified in the provided \refstruct{pmix_data_array_t}. If the provided array
+is \code{NULL}, then all resources shall be monitored. If no targets are provided in the associated
+\refarg{directives} array, then
+all processes in the session will be monitored.  Resource types may
 include any of the following:
 
-\begin{itemize}
-    \item \refattr{PMIX_MONITOR_RESOURCE_RATE}. If not provided, then the request will be treated as a one-shot
-            sampling of resource usage.
-    \item \refattr{PMIX_PROC_RESOURCE_USAGE}. If the \refstruct{pmix_data_array_t} is empty, then
-                    all process resource usage values shall be returned for all processes in the session.
-                    Optionally, the array of \refstruct{pmix_info_t} can specify the processes to be monitored, and/or the particular attributes to be included. Note that the values in the provided structures will be
-                    ignored (i.e., only the attribute keys are relevant) except where noted, and that the
-                    \refattr{PMIX_PROC_SAMPLE_TIME} will always be included in the returned data (there is no
-                    need to include it in the request). Optional attributes include:
     \begin{itemize}
-        \item \refattr{PMIX_PROCID}. Optionally specify the process to be monitored. Can include a
-                                     \refconst{PMIX_RANK_WILDCARD} to indicate that all processes
-                                     from a given namespace are to be included. If omitted, then
-                                     all processes in the session will be monitored. May be included
-                                     multiple times to fully specify all processes to be included.
         \item \refattr{PMIX_HOSTNAME}. Include the hostname where the process is located.
-        \item \refattr{PMIX_PROC_PID} Optionally specify the process to be monitored.
+        \item \refattr{PMIX_NODEID}. Include the node ID where the process is located.
+        \item \refattr{PMIX_PROC_PID}
         \item \refattr{PMIX_PROC_OS_STATE}
         \item \refattr{PMIX_PROC_TIME}
         \item \refattr{PMIX_PROC_PERCENT_CPU}
@@ -888,22 +1015,22 @@ \subsection{Monitoring attributes}
         \item \refattr{PMIX_PROC_CPU}
         \item \refattr{PMIX_PROC_SAMPLE_TIME}
     \end{itemize}
-    \item \refattr{PMIX_NODE_RESOURCE_USAGE}. If the \refstruct{pmix_data_array_t} is empty, then
-                    all node resource usage values shall be returned for all nodes in the session.
-                    Optionally, the array of \refstruct{pmix_info_t} can specify the nodes to be monitored (using the \refattr{PMIX_HOSTNAME} or \refattr{PMIX_NODEID} attributes), and/or the particular attributes to be included. Note that the values in the provided structures will be
-                    ignored (i.e., only the attribute keys are relevant) except where noted, and that the
-                    \refattr{PMIX_NODE_SAMPLE_TIME} will always be included in the returned data (there is no
-                    need to include it in the request). Optional
-                    attributes include:
+
+%
+\declareAttributeProvisional{PMIX_PROC_RESOURCE_USAGE}{"pmix.proc.resuse"}{pmix_data_array_t*}{
+Contains the reported resource usage of a given process. The process ID will be the first element in
+the array. Note that the \refattr{PMIX_PROC_SAMPLE_TIME} will always be included in the returned data
+(there is no need to include it in the request).
+}
+%
+\declareAttributeProvisional{PMIX_MONITOR_NODE_RESOURCE_USAGE}{"pmix.monitor.ndresuse"}{pmix_data_array_t*}{
+Monitor the resources specified in the provided \refstruct{pmix_data_array_t}. If the provided array
+is \code{NULL}, then all resources shall be monitored. If no targets are provided in the associated
+\refarg{directives} array, then
+all nodes in the session will be monitored. Resource types may
+include any of the following:
+
     \begin{itemize}
-        \item \refattr{PMIX_HOSTNAME}. Optionally specify the node to be monitored. May be included multiple
-                    times to fully specify all nodes to be included. Only
-                    hostname or node ID need be included (not both). If omitted, then all nodes in the session
-                    shall be monitored.
-        \item \refattr{PMIX_NODEID}. Optionally specify the process to be monitored. May be included multiple
-                    times to fully specify all nodes to be included. Only
-                    hostname or node ID need be included (not both). If omitted, then all nodes in the session
-                    shall be monitored.
         \item \refattr{PMIX_NODE_LOAD_AVG}
         \item \refattr{PMIX_NODE_LOAD_AVG5}
         \item \refattr{PMIX_NODE_LOAD_AVG15}
@@ -917,7 +1044,7 @@ \subsection{Monitoring attributes}
         \item \refattr{PMIX_NODE_MEM_MAPPED}
         \item \refattr{PMIX_DISK_RESOURCE_USAGE}. If the \refstruct{pmix_data_array_t} is empty, then
                     all disk resource usage values shall be returned for all disks attached to the node.
-                    Optionally, the array of \refstruct{pmix_info_t} can specify the disks to be monitored (using the \refattr{PMIX_DISK_ID} attribute), and/or the particular attributes to be included. Note that the values in the provided structures will be
+                    Optionally, the array of \refstruct{pmix_info_t} can specify the disks to be monitored (using the \refattr{PMIX_DISK_ID} attribute), and/or the particular attributes to be reported. Note that the values in the provided structures will be
                     ignored (i.e., only the attribute keys are relevant) except where noted, and that the
                     \refattr{PMIX_DISK_SAMPLE_TIME} will always be included in the returned data (there is no
                     need to include it in the request). Optional
@@ -939,7 +1066,7 @@ \subsection{Monitoring attributes}
         \end{itemize}
     \item \refattr{PMIX_NETWORK_RESOURCE_USAGE}.  If the \refstruct{pmix_data_array_t} is empty, then
                     all network resource usage values shall be returned for all interfaces on the node.
-                    Optionally, the array of \refstruct{pmix_info_t} can specify the networks to be monitored (using the \refattr{PMIX_NETWORK_ID} attribute), and/or the particular attributes to be included. Note that the values in the provided structures will be
+                    Optionally, the array of \refstruct{pmix_info_t} can specify the networks to be monitored (using the \refattr{PMIX_NETWORK_ID} attribute), and/or the particular attributes to be reported. Note that the values in the provided structures will be
                     ignored (i.e., only the attribute keys are relevant) except where noted, and that the
                     \refattr{PMIX_NET_SAMPLE_TIME} will always be included in the returned data (there is no
                     need to include it in the request). Optional
@@ -958,6 +1085,13 @@ \subsection{Monitoring attributes}
 \end{itemize}
 }
 
+%
+\declareAttributeProvisional{{PMIX_NODE_RESOURCE_USAGE}{"pmix.node.resuse"}{pmix_data_array_t*}{
+Contains the reported resource usage of a given node. The hostname and/or node ID will be the first element in
+the array. Note that the \refattr{PMIX_NODE_SAMPLE_TIME} will always be included in the returned data
+(there is no need to include it in the request).
+}
+
 %%%%%%%%%%%
 \versionMarkerProvisional{6.0}
 \subsection{Resource usage attributes}

Chap_API_Struct.tex

@@ -2548,6 +2548,9 @@ \section{Generalized Data Types Used for Packing/Unpacking}
 \declareconstitemvalue{PMIX_STOR_ACCESS_TYPE}{69}
 Bitmask specifying different storage system access types. (\refstruct{pmix_storage_access_type_t}).
 %
+\declareconstitemvalueProvisional{PMIX_NODE_PID}{70}
+Structure containing the hostname and pid of a process
+%
 \declareconstitemvalue{PMIX_DATA_TYPE_MAX}{500}
 A starting point for implementer-specific data types.
 Values above this are guaranteed not to conflict with \ac{PMIx} values.