Some revisions

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

Author: rhc54

Chap_API_Job_Mgmt.tex

@@ -701,13 +701,13 @@ \subsection{\code{PMIx_Process_monitor}}
 %%%%
 \descr
 
-Request that application processes be monitored via several possible methods.
-For example, that the server monitor this process for periodic heartbeats as an indication that the process has not become ``wedged''.
+Request that application processes and/or files be monitored via several possible methods.
+For example, that the server monitor a given process for periodic heartbeats as an indication that the process has not become ``wedged''.
 When a monitor detects the specified alarm condition, it will generate an event notification using the provided error code and passing along any available relevant information.
 It is up to the caller to register a corresponding event handler.
 
 The \refarg{monitor} argument is an attribute indicating the type of monitor being requested.
-For example, \refattr{PMIX_MONITOR_FILE} to indicate that the requestor is asking that a file be monitored.
+For example, \refattr{PMIX_MONITOR_FILE_CHANGES} to indicate that the requestor is asking that a file be monitored.
 
 The \refarg{error} argument is the status code to be used when generating an event notification alerting that the monitor has been triggered.
 The range of the notification defaults to \refconst{PMIX_RANGE_NAMESPACE}.
@@ -770,13 +770,13 @@ \subsection{\code{PMIx_Process_monitor_nb}}
         \item \refattr{PMIX_MONITOR_HEARTBEAT_DROPS}
     \end{itemize}
     \item \refattr{PMIX_SEND_HEARTBEAT}
-    \item \refattr{PMIX_MONITOR_FILE} The associated \refarg{directives} array may include any of the following:
+    \item \refattr{PMIX_MONITOR_FILE_CHANGES} The associated \refarg{directives} array may include any of the following:
     \begin{itemize}
-        \item \refattr{PMIX_MONITOR_FILE_SIZE}
-        \item \refattr{PMIX_MONITOR_FILE_ACCESS}
-        \item \refattr{PMIX_MONITOR_FILE_MODIFY}
         \item \refattr{PMIX_MONITOR_FILE_CHECK_TIME}
         \item \refattr{PMIX_MONITOR_FILE_DROPS}
+        \item \refattr{PMIX_MONITOR_TARGET_FILES}
+        \item \refattr{PMIX_MONITOR_TARGET_NODES}. Monitor the given files on the specified nodes, where present.
+        \item \refattr{PMIX_MONITOR_TARGET_NODEIDS}. Monitor the given files on the specified nodes, where present.
     \end{itemize}
     \item \refattr{PMIX_MONITOR_PROC_RESOURCE_USAGE} The associated \refarg{directives} array may include any of the following:
     \begin{itemize}
@@ -793,6 +793,22 @@ \subsection{\code{PMIx_Process_monitor_nb}}
         \item \refattr{PMIX_MONITOR_TARGET_NODEIDS}
         \item \refattr{PMIX_MONITOR_TARGET_PROCS}. Monitor the nodes where the specified processes are located.
     \end{itemize}
+    \item \refattr{PMIX_MONITOR_DISK_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_DISKS}
+        \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}
+    \item \refattr{PMIX_MONITOR_NETWORK_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_NETS}
+        \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:
@@ -860,17 +876,18 @@ \subsection{Monitoring Datatypes}
 \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.
+The \refstruct{pmix_node_pid_t} structure contains the hostname (or nodeID) 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}uint32_t nodeid; \\
 \hspace*{4\sigspace}pid_t pid; \\
 \} pmix_node_pid_t;
 }
 
-The \refarg{pid} field contains the \code{pid_t} of the process, while the \refarg{hostname} is the name of the node where the process is executing.
+The \refarg{pid} field contains the \code{pid_t} of the process, while the \refarg{hostname} and/or \refarg{nodeid} identify the node where the process is executing.
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 \subsubsection{Node PID support functions}
@@ -973,20 +990,34 @@ \subsection{Monitoring attributes}
 Number of heartbeats that can be missed before generating the event.
 }
 %
-\declareAttribute{PMIX_MONITOR_FILE}{"pmix.monitor.fmon"}{char*}{
-Register to monitor file for signs of life - the value contains the filename to be monitored.
+\declareAttributeProvisional{PMIX_MONITOR_FILE_CHANGES}{"pmix.monitor.fchg"}{pmix_data_array_t*}{
+Monitor the file characteristics specified in the provided \refstruct{pmix_data_array_t} of \refstruct{pmix_info_t}. If the provided array
+is \code{NULL}, then all optional file characteristics shall be monitored. Target filenames **must** be provided in the associated
+\refarg{directives} array. If no target nodes are specified, then the target files will be monitored on all nodes in the session where they are present.  Note that the values in the provided structures will be
+ignored (i.e., only the attribute keys are relevant) except where noted. Optional
+attributes include:
+
+    \begin{itemize}
+        \refattr{PMIX_MONITOR_FILE_SIZE}
+        \refattr{PMIX_MONITOR_FILE_ACCESS}
+        \refattr{PMIX_MONITOR_FILE_MODIFY}
+    \end{itemize}
+}
+%
+\declareAttributeProvisional{PMIX_MONITOR_TARGET_FILES}{"pmix.monitor.fmon"}{pmix_data_array_t*}{
+Array of string filenames to be monitored for signs of life.
 }
 %
 \declareAttribute{PMIX_MONITOR_FILE_SIZE}{"pmix.monitor.fsize"}{bool}{
-Monitor given file is growing in size to determine if the application is running.
+Monitor that file is growing in size 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.
+Monitor that time since last access has changed 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.
+Monitor that time since last modified has changed to determine if the application is running.
 }
 %
 \declareAttribute{PMIX_MONITOR_FILE_CHECK_TIME}{"pmix.monitor.ftime"}{uint32_t}{
@@ -1013,17 +1044,28 @@ \subsection{Monitoring attributes}
 }
 %
 \declareAttributeProvisional{PMIX_MONITOR_TARGET_NODES}{"pmix.monitor.tgtnode"}{pmix_data_array_t*}{
-Array of host names to be monitored
+Array of string 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}{
+\declareAttributeProvisional{PMIX_MONITOR_TARGET_DISKS}{"pmix.monitor.tgtdks"}{pmix_data_array_t*}{
+Array of strings representing \refattr{PMIX_DISK_ID}s to be monitored
+}
+%
+\declareAttributeProvisional{PMIX_MONITOR_TARGET_NETS}{"pmix.monitor.tgtnets"}{pmix_data_array_t*}{
+Array of strings representing \refattr{PMIX_NETWORK_ID}s to be monitored
+}
+%
+\declareAttributeProvisional{PMIX_MONITOR_RESOURCE_RATE}{"pmix.monitor.resrate"}{uint32_t}{
 Monitor resource usage every N seconds, where N is the value provided by the attribute.
 }
 %
+\declareAttributeProvisional{PMIX_MONITOR_LOCAL_ONLY}{"pmix.monitor.local"}{bool}{
+Restrict data collection to the local host, regardless of any provided targets}
+%
 \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} of \refstruct{pmix_info_t}. If the provided array
 is \code{NULL}, then all resources shall be monitored. If no targets are provided in the associated
@@ -1074,51 +1116,54 @@ \subsection{Monitoring attributes}
         \item \refattr{PMIX_NODE_MEM_SWAP_TOTAL}
         \item \refattr{PMIX_NODE_MEM_SWAP_FREE}
         \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 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
-                    attributes include:
-        \begin{itemize}
-            \item \refattr{PMIX_DISK_ID}. Optionally specify the disk to be monitored. If omitted, then all disks
-                    attached to the node will be monitored.
-            \item \refattr{PMIX_DISK_READ_COMPLETED}
-            \item \refattr{PMIX_DISK_READ_MERGED}
-            \item \refattr{PMIX_DISK_READ_SECTORS}
-            \item \refattr{PMIX_DISK_READ_MILLISEC}
-            \item \refattr{PMIX_DISK_WRITE_COMPLETED}
-            \item \refattr{PMIX_DISK_WRITE_MERGED}
-            \item \refattr{PMIX_DISK_WRITE_SECTORS}
-            \item \refattr{PMIX_DISK_WRITE_MILLISEC}
-            \item \refattr{PMIX_DISK_IO_IN_PROGRESS}
-            \item \refattr{PMIX_DISK_IO_MILLISEC}
-            \item \refattr{PMIX_DISK_IO_WEIGHTED}
-            \item \refattr{PMIX_DISK_SAMPLE_TIME}
-        \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 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
-                    attributes include:
-        \begin{itemize}
-            \item \refattr{PMIX_NETWORK_ID}. Optionally specify the interface to be monitored. If omitted, then all
-                    interfaces on the node will be monitored.
-            \item \refattr{PMIX_NET_RECVD_BYTES}
-            \item \refattr{PMIX_NET_RECVD_PCKTS}
-            \item \refattr{PMIX_NET_RECVD_ERRS}
-            \item \refattr{PMIX_NET_SENT_BYTES}
-            \item \refattr{PMIX_NET_SENT_PCKTS}
-            \item \refattr{PMIX_NET_SENT_ERRS}
-            \item \refattr{PMIX_NET_SAMPLE_TIME}.
-        \end{itemize}
         \item \refattr{PMIX_NODE_SAMPLE_TIME}.
     \end{itemize}
 }
 
+\declareAttributeProvisional{PMIX_MONITOR_DISK_RESOURCE_USAGE}{"pmix.monitor.dkresuse"}{pmix_data_array_t*}{
+Monitor the resources specified in the provided \refstruct{pmix_data_array_t} of \refstruct{pmix_info_t}. If the provided array
+is \code{NULL}, then all disk resources shall be monitored. If no \refattr{PMIX_DISK_ID} targets are provided in the associated
+\refarg{directives} array, then
+all disks on the local node (or on the specified target nodes, if given) will be monitored. 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 attributes include:
+
+    \begin{itemize}
+        \item \refattr{PMIX_DISK_READ_COMPLETED}
+        \item \refattr{PMIX_DISK_READ_MERGED}
+        \item \refattr{PMIX_DISK_READ_SECTORS}
+        \item \refattr{PMIX_DISK_READ_MILLISEC}
+        \item \refattr{PMIX_DISK_WRITE_COMPLETED}
+        \item \refattr{PMIX_DISK_WRITE_MERGED}
+        \item \refattr{PMIX_DISK_WRITE_SECTORS}
+        \item \refattr{PMIX_DISK_WRITE_MILLISEC}
+        \item \refattr{PMIX_DISK_IO_IN_PROGRESS}
+        \item \refattr{PMIX_DISK_IO_MILLISEC}
+        \item \refattr{PMIX_DISK_IO_WEIGHTED}
+        \item \refattr{PMIX_DISK_SAMPLE_TIME}
+    \end{itemize}
+
+\declareAttributeProvisional{PMIX_MONITOR_NETWORK_RESOURCE_USAGE}{"pmix.monitor.netresuse"}{pmix_data_array_t*}{
+Monitor the resources specified in the provided \refstruct{pmix_data_array_t} of \refstruct{pmix_info_t}. If the provided array
+is \code{NULL}, then all network resources shall be monitored. If no \refattr{PMIX_NETWORK_ID} targets are provided in the associated
+\refarg{directives} array, then
+all network interfaces on the local node (or on the specified target nodes, if given) will be monitored. 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 attributes include:
+
+    \begin{itemize}
+        \item \refattr{PMIX_NET_RECVD_BYTES}
+        \item \refattr{PMIX_NET_RECVD_PCKTS}
+        \item \refattr{PMIX_NET_RECVD_ERRS}
+        \item \refattr{PMIX_NET_SENT_BYTES}
+        \item \refattr{PMIX_NET_SENT_PCKTS}
+        \item \refattr{PMIX_NET_SENT_ERRS}
+        \item \refattr{PMIX_NET_SAMPLE_TIME}.
+    \end{itemize}
+
+
 %%%%%%%%%%%
 \versionMarkerProvisional{6.0}
 \subsection{Resource usage attributes}
@@ -1136,7 +1181,8 @@ \subsubsection{Process resource usage}
 the first element containing the ID of the process (marked by either the \refattr{PMIX_PROCID}
 or \refattr{PMIX_PROC_PID} key)
 whose usage is reported in the array. The list of included information may vary across
-implementations and \acp{OS}, depending upon availability and access restrictions. Except for
+implementations and \acp{OS}, depending upon availability and access restrictions, and the
+provided list of requested values. Except for
 the process ID as the first element, ordering of information in the array is arbitrary.
 }
 
@@ -1179,7 +1225,7 @@ \subsubsection{Process resource usage}
 \item \declareAttributeProvisional{PMIX_PROC_CPU}{"pmix.proc.cpu"}{uint16_t}{
     Processor that process last executed on
 }
-\item \declareAttributeProvisional{PMIX_PROC_SAMPLE_TIME}{"pmix.proc.samptime"}{struct timeval}{
+\item \declareAttributeProvisional{PMIX_PROC_SAMPLE_TIME}{"pmix.proc.samptime"}{time_t}{
     Time when sample was taken
 }
 \end{itemize}
@@ -1195,7 +1241,8 @@ \subsubsection{Disk resource usage}
 An array of \refstruct{pmix_info_t} describing the resource usage of the specified disk, with
 the first element containing the string name of the disk (marked by the \refattr{PMIX_DISK_ID} key)
 whose usage is reported in the array. The list of included information may vary across
-implementations and \acp{OS}, depending upon availability and access restrictions. Except for
+implementations and \acp{OS}, depending upon availability and access restrictions, and the
+provided list of requested values. Except for
 the disk ID as the first element, ordering of information in the array is arbitrary.
 }
 
@@ -1236,7 +1283,7 @@ \subsubsection{Disk resource usage}
 Number of IOs in progress times the number of milliseconds spent doing IO since
 last update of the field - indicator of backlog that may be accumulating
 }
-\item \declareAttributeProvisional{PMIX_DISK_SAMPLE_TIME}{"pmix.disk.samptime"}{struct timeval}{
+\item \declareAttributeProvisional{PMIX_DISK_SAMPLE_TIME}{"pmix.disk.samptime"}{time_t}{
     Time when sample was taken
 }
 \end{itemize}
@@ -1251,7 +1298,8 @@ \subsubsection{Network resource usage}
 An array of \refstruct{pmix_info_t} describing the resource usage of the specified network, with
 the first element containing the string name of the interface (marked by the \refattr{PMIX_NETWORK_ID} key)
 whose usage is reported in the array. The list of included information may vary across
-implementations and \acp{OS}, depending upon availability and access restrictions. Except for
+implementations and \acp{OS}, depending upon availability and access restrictions, and the
+provided list of requested values. Except for
 the network ID as the first element, ordering of information in the array is arbitrary.
 }
 
@@ -1276,7 +1324,7 @@ \subsubsection{Network resource usage}
 \item \declareAttributeProvisional{PMIX_NET_SENT_ERRS}{"pmix.net.snterr"}{uint64_t}{
 Number of send errors
 }
-\item \declareAttributeProvisional{PMIX_NET_SAMPLE_TIME}{"pmix.net.samptime"}{struct timeval}{
+\item \declareAttributeProvisional{PMIX_NET_SAMPLE_TIME}{"pmix.net.samptime"}{time_t}{
     Time when sample was taken
 }
 \end{itemize}
@@ -1289,7 +1337,8 @@ \subsubsection{Node resource usage}
 with the first element containing
 the ID of the node (marked by the \refattr{PMIX_HOSTNAME} or \refattr{PMIX_NODEID} key) whose usage
 is reported in the array. The list of included information may vary across
-implementations and \acp{OS}, depending upon availability and access restrictions. Except for
+implementations and \acp{OS}, depending upon availability and access restrictions, and the
+provided list of requested values. Except for
 the node ID as the first element, ordering of information in the array is arbitrary.
 }
 
@@ -1331,9 +1380,9 @@ \subsubsection{Node resource usage}
 \item \declareAttributeProvisional{PMIX_NODE_MEM_MAPPED}{"pmix.node.mmap"}{float}{
 files which have been mmapped, such as libraries. Note that some kernel configurations might consider all pages part of a larger allocation (e.g., THP) as “mapped”, as soon as a single page is mapped. In MBytes
 }
-\item \refattr{PMIX_DISK_RESOURCE_USAGE} One for each disk attached to the node.
-\item \refattr{PMIX_NETWORK_RESOURCE_USAGE} One for each network interface on the node.
-\item \declareAttributeProvisional{PMIX_NODE_SAMPLE_TIME}{"pmix.node.samptime"}{struct timeval}{
+\item \refattr{PMIX_DISK_RESOURCE_USAGE} One for each disk attached to the node, if requested.
+\item \refattr{PMIX_NETWORK_RESOURCE_USAGE} One for each network interface on the node, if requested.
+\item \declareAttributeProvisional{PMIX_NODE_SAMPLE_TIME}{"pmix.node.samptime"}{time_t}{
     Time when sample was taken
 }
 \end{itemize}

Chap_API_Struct.tex

@@ -2548,7 +2548,7 @@ \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}
+\declareconstitemvalueProvisional{PMIX_NODE_PID}{73}
 Structure containing the hostname and pid of a process
 %
 \declareconstitemvalue{PMIX_DATA_TYPE_MAX}{500}