Add several IOF attributes

Chap_API_Server.tex

@@ -109,6 +109,7 @@ \subsection{\code{PMIx_server_init}}
 \pasteAttributeItem{PMIX_SERVER_ENABLE_MONITORING}
 \pasteAttributeItem{PMIX_HOMOGENEOUS_SYSTEM}
 \pasteAttributeItem{PMIX_SINGLETON}
+\pasteAttributeItem{PMIX_IOF_LOCAL_OUTPUT}
 
 \optattrend
 

Chap_API_Tools.tex

@@ -293,9 +293,16 @@ \subsection{Direct launch}
     \item \pasteAttributeItem{PMIX_IOF_DROP_NEWEST}
     \item \pasteAttributeItem{PMIX_IOF_BUFFERING_SIZE}
     \item \pasteAttributeItem{PMIX_IOF_BUFFERING_TIME}
+    \item \pasteAttributeItem{PMIX_IOF_OUTPUT_RAW}
     \item \pasteAttributeItem{PMIX_IOF_TAG_OUTPUT}
     \item \pasteAttributeItem{PMIX_IOF_TIMESTAMP_OUTPUT}
     \item \pasteAttributeItem{PMIX_IOF_XML_OUTPUT}
+    \item \pasteAttributeItem{PMIX_IOF_RANK_OUTPUT}
+    \item \pasteAttributeItem{PMIX_IOF_OUTPUT_TO_FILE}
+    \item \pasteAttributeItem{PMIX_IOF_OUTPUT_TO_DIRECTORY}
+    \item \pasteAttributeItem{PMIX_IOF_FILE_PATTERN}
+    \item \pasteAttributeItem{PMIX_IOF_FILE_ONLY}
+    \item \pasteAttributeItem{PMIX_IOF_MERGE_STDERR_STDOUT}
     \item \pasteAttributeItem{PMIX_NOHUP}
     \item \pasteAttributeItem{PMIX_NOTIFY_JOB_EVENTS}
     \item \pasteAttributeItem{PMIX_NOTIFY_COMPLETION}
@@ -306,6 +313,14 @@ \subsection{Direct launch}
     \item \pasteAttributeItem{PMIX_DEBUG_WAIT_FOR_NOTIFY}
 \end{itemize}
 
+
+\adviceuserstart
+The \refattr{PMIX_IOF_FILE_ONLY} indicates output is directed to files and
+no copy is sent back to the application.  For example, this can be combined with
+\refattr{PMIX_IOF_OUTPUT_TO_FILE} or \refattr{PMIX_IOF_OUTPUT_TO_DIRECTORY} to
+only output to files.
+\adviceuserend
+
 The tool then calls the \refapi{PMIx_Spawn} \ac{API} so that the \ac{PMIx} library can communicate the spawn request to the server.
 
 Upon receipt, the \ac{PMIx} server library passes the spawn request to its host \ac{RM} daemon for processing via the \refapi{pmix_server_spawn_fn_t} server module function. If this callback was not provided, then the \ac{PMIx} server library will return the \refconst{PMIX_ERR_NOT_SUPPORTED} error status.
@@ -594,6 +609,13 @@ \subsection{Forwarding stdout/stderr}
     \item \pasteAttributeItem{PMIX_IOF_TAG_OUTPUT}
     \item \pasteAttributeItem{PMIX_IOF_TIMESTAMP_OUTPUT}
     \item \pasteAttributeItem{PMIX_IOF_XML_OUTPUT}
+    \item \pasteAttributeItem{PMIX_IOF_RANK_OUTPUT}
+    \item \pasteAttributeItem{PMIX_IOF_OUTPUT_TO_FILE}
+    \item \pasteAttributeItem{PMIX_IOF_OUTPUT_TO_DIRECTORY}
+    \item \pasteAttributeItem{PMIX_IOF_FILE_PATTERN}
+    \item \pasteAttributeItem{PMIX_IOF_FILE_ONLY}
+    \item \pasteAttributeItem{PMIX_IOF_MERGE_STDERR_STDOUT}
+
 \end{itemize}
 
 The \ac{PMIx} client in the tool is responsible for formatting the output stream. Note that output from multiple processes will often be interleaved due to variations in arrival time - ordering of output is not guaranteed across processes and/or nodes.
@@ -676,6 +698,14 @@ \subsection{IO Forwarding attributes}
 
 The following attributes are used to control \ac{IO} forwarding behavior at the request of tools. Use of the attributes is optional - any option not provided will revert to some implementation-specific value.
 
+%
+\declareAttributeNEW{PMIX_IOF_LOCAL_OUTPUT}{"pmix.iof.local"}{bool}{
+Write output streams to local stdout/err
+}
+%
+\declareAttributeNEW{PMIX_IOF_MERGE_STDERR_STDOUT}{"pmix.iof.mrg"}{bool}{
+Merge stdout and stderr streams from application procs
+}
 %
 \declareAttribute{PMIX_IOF_CACHE_SIZE}{"pmix.iof.csize"}{uint32_t}{
 The requested size of the \ac{PMIx} server cache in bytes for each specified channel. By default, the server is allowed (but not required) to drop all bytes received beyond the max size.
@@ -697,6 +727,10 @@ \subsection{IO Forwarding attributes}
 Max time in seconds to buffer \ac{IO} before delivering it. Used in conjunction with buffering size, this prevents \ac{IO} from being held indefinitely while waiting for another payload to arrive.
 }
 %
+\declareAttributeNEW{PMIX_IOF_OUTPUT_RAW}{"pmix.iof.raw"}{bool}{
+Do not buffer output to be written as complete lines - output characters as the stream delivers them
+}
+%
 \declareAttribute{PMIX_IOF_COMPLETE}{"pmix.iof.cmp"}{bool}{
 Indicates that the specified \ac{IO} channel has been closed by the source.
 }
@@ -709,6 +743,10 @@ \subsection{IO Forwarding attributes}
 Requests that output be marked with the time at which the data was received by the tool - note that this will differ from the time at which the data was collected from the source.
 }
 %
+\declareAttributeNEW{PMIX_IOF_RANK_OUTPUT}{"pmix.iof.rank"}{bool}{
+Tag output with the rank it came from
+}
+%
 \declareAttribute{PMIX_IOF_XML_OUTPUT}{"pmix.iof.xml"}{bool}{
 Requests that output be formatted in \ac{XML}.
 }
@@ -724,7 +762,23 @@ \subsection{IO Forwarding attributes}
 \declareAttributeNEW{PMIX_IOF_REDIRECT}{"pmix.iof.redir"}{bool}{
 Requests that the host environment intercept the specified output stream(s) and deliver it to the requesting tool instead of its current final destination. This might be used, for example, during a debugging procedure to avoid injection of debugger-related output into the application’s results file. The original output stream(s) destination is restored upon termination of the tool.
 }
-
+%
+\declareAttributeNEW{PMIX_IOF_OUTPUT_TO_FILE}{"pmix.iof.file"}{char*}{
+Direct application output into files of form "<filename>.<nspace>.<rank>.stdout" (for \code{stdout}) and "<filename>.<nspace>.<rank>.stderr" (for \code{stderr}). If \refattr{PMIX_IOF_MERGE_STDERR_STDOUT} was given, then only the \code{stdout} file will be created and both streams will be written into it.
+}
+%
+\declareAttributeNEW{PMIX_IOF_OUTPUT_TO_DIRECTORY}{"pmix.iof.dir"}{char*}{
+Direct application output into files of form "<directory>/<nspace>/rank.<rank>/stdout" (for \code{stdout}) and "<directory>/<nspace>/rank.<rank>/stderr" (for \code{stderr}). If \refattr{PMIX_IOF_MERGE_STDERR_STDOUT} was given, then only the \code{stdout} file will be created and both streams will be written into it.
+}
+%
+\declareAttributeNEW{PMIX_IOF_FILE_PATTERN}{"pmix.iof.fpt"}{bool}{
+Specified output file is to be treated as a pattern and not automatically annotated by nspace, rank, or other parameters. The pattern can use \code{\%n} for the namespace, and \code{\%r} for the rank wherever those quantities are to be placed. The resulting filename will be appended with ".stdout" for the \code{stdout} stream and ".stderr" for the \code{stderr} stream. If \refattr{PMIX_IOF_MERGE_STDERR_STDOUT} was given, then only the \code{stdout} file will be created and both streams will be written into it.
+}
+%
+\declareAttributeNEW{PMIX_IOF_FILE_ONLY}{"pmix.iof.fonly"}{bool}{
+Output only into designated files - do not also output a copy to the console's stdout/stderr
+}
+%
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@@ -1185,6 +1239,7 @@ \subsection{\code{PMIx_tool_init}}
 \pasteAttributeItemEnd{}
 \pasteAttributeItem{PMIX_EXTERNAL_PROGRESS}
 \pasteAttributeItem{PMIX_EVENT_BASE}
+\pasteAttributeItem{PMIX_IOF_LOCAL_OUTPUT}
 
 \optattrend
 

Chap_Revisions.tex

@@ -1292,3 +1292,19 @@ \subsection{Added Attributes (Provisional)}
 
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%% History: Version 4.2
+\section{Version 4.2: TBD}
+
+The v4.2 update includes the following changes from the v4.1 document:
+
+\subsection{Added Attributes (Provisional)}
+
+\littleheader{Tool attributes}
+\pasteAttributeItem{PMIX_IOF_LOCAL_OUTPUT}
+\pasteAttributeItem{PMIX_IOF_MERGE_STDERR_STDOUT}
+\pasteAttributeItem{PMIX_IOF_OUTPUT_RAW}
+\pasteAttributeItem{PMIX_IOF_RANK_OUTPUT}
+\pasteAttributeItem{PMIX_IOF_OUTPUT_TO_FILE}
+\pasteAttributeItem{PMIX_IOF_OUTPUT_TO_DIRECTORY}
+\pasteAttributeItem{PMIX_IOF_FILE_PATTERN}
+\pasteAttributeItem{PMIX_IOF_FILE_ONLY}