\hypertarget{iof_8h}{\section{orte/mca/iof/iof.h File Reference}
\label{iof_8h}\index{orte/mca/iof/iof.\+h@{orte/mca/iof/iof.\+h}}
}


I/\+O Forwarding Service The I/\+O forwarding service (I\+O\+F) is used to connect stdin, stdout, and stderr file descriptor streams from M\+P\+I processes to the user.  


{\ttfamily \#include \char`\"{}orte\+\_\+config.\+h\char`\"{}}\\*
{\ttfamily \#include \char`\"{}orte/types.\+h\char`\"{}}\\*
{\ttfamily \#include \char`\"{}opal/mca/mca.\+h\char`\"{}}\\*
{\ttfamily \#include \char`\"{}opal/mca/crs/crs.\+h\char`\"{}}\\*
{\ttfamily \#include \char`\"{}opal/mca/crs/base/base.\+h\char`\"{}}\\*
{\ttfamily \#include \char`\"{}iof\+\_\+types.\+h\char`\"{}}\\*
\subsection*{Data Structures}
\begin{DoxyCompactItemize}
\item 
struct \hyperlink{structorte__iof__base__module__2__0__0__t}{orte\+\_\+iof\+\_\+base\+\_\+module\+\_\+2\+\_\+0\+\_\+0\+\_\+t}
\begin{DoxyCompactList}\small\item\em I\+O\+F module. \end{DoxyCompactList}\item 
struct \hyperlink{structorte__iof__base__component__2__0__0__t}{orte\+\_\+iof\+\_\+base\+\_\+component\+\_\+2\+\_\+0\+\_\+0\+\_\+t}
\end{DoxyCompactItemize}
\subsection*{Macros}
\begin{DoxyCompactItemize}
\item 
\#define {\bfseries O\+R\+T\+E\+\_\+\+I\+O\+F\+\_\+\+B\+A\+S\+E\+\_\+\+V\+E\+R\+S\+I\+O\+N\+\_\+2\+\_\+0\+\_\+0}
\end{DoxyCompactItemize}
\subsection*{Typedefs}
\begin{DoxyCompactItemize}
\item 
typedef int($\ast$ \hyperlink{iof_8h_ad0f40f3f458ced4170a896166e0b047f}{orte\+\_\+iof\+\_\+base\+\_\+push\+\_\+fn\+\_\+t} )(const \hyperlink{structorte__process__name__t}{orte\+\_\+process\+\_\+name\+\_\+t} $\ast$peer, orte\+\_\+iof\+\_\+tag\+\_\+t src\+\_\+tag, int fd)
\begin{DoxyCompactList}\small\item\em Explicitly push data from the specified input file descriptor to the stdin of the indicated peer(s). \end{DoxyCompactList}\item 
typedef int($\ast$ \hyperlink{iof_8h_a3e86e058e0447a72da3ad6e4e47ecc6b}{orte\+\_\+iof\+\_\+base\+\_\+pull\+\_\+fn\+\_\+t} )(const \hyperlink{structorte__process__name__t}{orte\+\_\+process\+\_\+name\+\_\+t} $\ast$peer, orte\+\_\+iof\+\_\+tag\+\_\+t source\+\_\+tag, int fd)
\begin{DoxyCompactList}\small\item\em Explicitly pull data from the specified set of S\+O\+U\+R\+C\+E peers and dump to the indicated output file descriptor. \end{DoxyCompactList}\item 
\hypertarget{iof_8h_ae39b9c70b275975ccd6c181748fec761}{typedef int($\ast$ \hyperlink{iof_8h_ae39b9c70b275975ccd6c181748fec761}{orte\+\_\+iof\+\_\+base\+\_\+close\+\_\+fn\+\_\+t} )(const \hyperlink{structorte__process__name__t}{orte\+\_\+process\+\_\+name\+\_\+t} $\ast$peer, orte\+\_\+iof\+\_\+tag\+\_\+t source\+\_\+tag)}\label{iof_8h_ae39b9c70b275975ccd6c181748fec761}

\begin{DoxyCompactList}\small\item\em Close the specified iof stream(s) from the indicated peer(s) \end{DoxyCompactList}\item 
\hypertarget{iof_8h_abd1e47ca041387f528d7c92843527cf2}{typedef int($\ast$ {\bfseries orte\+\_\+iof\+\_\+base\+\_\+finalize\+\_\+fn\+\_\+t} )(void)}\label{iof_8h_abd1e47ca041387f528d7c92843527cf2}

\item 
\hypertarget{iof_8h_a33f9d8b2c8fdf1e3ed7e068ff81391f4}{typedef int($\ast$ \hyperlink{iof_8h_a33f9d8b2c8fdf1e3ed7e068ff81391f4}{orte\+\_\+iof\+\_\+base\+\_\+ft\+\_\+event\+\_\+fn\+\_\+t} )(int state)}\label{iof_8h_a33f9d8b2c8fdf1e3ed7e068ff81391f4}

\begin{DoxyCompactList}\small\item\em F\+T Event Notification. \end{DoxyCompactList}\item 
\hypertarget{iof_8h_a47be1edc0197388d098783e949d7f215}{typedef struct \\*
\hyperlink{structorte__iof__base__module__2__0__0__t}{orte\+\_\+iof\+\_\+base\+\_\+module\+\_\+2\+\_\+0\+\_\+0\+\_\+t} {\bfseries orte\+\_\+iof\+\_\+base\+\_\+module\+\_\+2\+\_\+0\+\_\+0\+\_\+t}}\label{iof_8h_a47be1edc0197388d098783e949d7f215}

\item 
\hypertarget{iof_8h_aec821d5356426fd20293ffd1d3a2103e}{typedef \\*
\hyperlink{structorte__iof__base__module__2__0__0__t}{orte\+\_\+iof\+\_\+base\+\_\+module\+\_\+2\+\_\+0\+\_\+0\+\_\+t} {\bfseries orte\+\_\+iof\+\_\+base\+\_\+module\+\_\+t}}\label{iof_8h_aec821d5356426fd20293ffd1d3a2103e}

\item 
\hypertarget{iof_8h_af792b4bfdcb3ee09408cc0f001c1b011}{typedef struct \\*
\hyperlink{structorte__iof__base__component__2__0__0__t}{orte\+\_\+iof\+\_\+base\+\_\+component\+\_\+2\+\_\+0\+\_\+0\+\_\+t} {\bfseries orte\+\_\+iof\+\_\+base\+\_\+component\+\_\+2\+\_\+0\+\_\+0\+\_\+t}}\label{iof_8h_af792b4bfdcb3ee09408cc0f001c1b011}

\item 
\hypertarget{iof_8h_ace19805c77577a5f7d1a4e536cda5c30}{typedef struct \\*
\hyperlink{structorte__iof__base__component__2__0__0__t}{orte\+\_\+iof\+\_\+base\+\_\+component\+\_\+2\+\_\+0\+\_\+0\+\_\+t} {\bfseries orte\+\_\+iof\+\_\+base\+\_\+component\+\_\+t}}\label{iof_8h_ace19805c77577a5f7d1a4e536cda5c30}

\end{DoxyCompactItemize}
\subsection*{Variables}
\begin{DoxyCompactItemize}
\item 
\hypertarget{iof_8h_ad8eac2b0693a5447adedcd5a6e2c165a}{B\+E\+G\+I\+N\+\_\+\+C\+\_\+\+D\+E\+C\+L\+S typedef int($\ast$ {\bfseries orte\+\_\+iof\+\_\+base\+\_\+init\+\_\+fn\+\_\+t} )(void)}\label{iof_8h_ad8eac2b0693a5447adedcd5a6e2c165a}

\item 
\hypertarget{iof_8h_a127c0532531306e14f5038c6f9d64978}{O\+R\+T\+E\+\_\+\+D\+E\+C\+L\+S\+P\+E\+C \\*
\hyperlink{structorte__iof__base__module__2__0__0__t}{orte\+\_\+iof\+\_\+base\+\_\+module\+\_\+t} {\bfseries orte\+\_\+iof}}\label{iof_8h_a127c0532531306e14f5038c6f9d64978}

\end{DoxyCompactItemize}


\subsection{Detailed Description}
I/\+O Forwarding Service The I/\+O forwarding service (I\+O\+F) is used to connect stdin, stdout, and stderr file descriptor streams from M\+P\+I processes to the user. 

The design is fairly simple\+: when a proc is spawned, the I\+O\+F establishes connections between its stdin, stdout, and stderr to a corresponding I\+O\+F stream. In addition, the I\+O\+F designates a separate stream for passing O\+M\+P\+I/\+O\+R\+T\+E internal diagnostic/help output to mpirun. This is done specifically to separate such output from the user's stdout/err -\/ basically, it allows us to present it to the user in a separate format for easier recognition. Data read from a source on any stream (e.\+g., printed to stdout by the proc) is relayed by the local daemon to the other end of the stream -\/ i.\+e., stdin is relayed to the local proc, while stdout/err is relayed to mpirun. Thus, the eventual result is to connect A\+L\+L streams to/from the application process and mpirun.

Note\+: By default, data read from stdin is forwarded -\/only-\/ to rank=0. Stdin for all other procs is tied to \char`\"{}/dev/null\char`\"{}.

External tools can \char`\"{}pull\char`\"{} copies of stdout/err and the diagnostic stream from mpirun for any process. In this case, mpirun will send a copy of the output to the \char`\"{}pulling\char`\"{} process. Note that external tools cannot \char`\"{}push\char`\"{} something into stdin unless the user specifically directed that stdin remain open, nor under any conditions \char`\"{}pull\char`\"{} a copy of the stdin being sent to rank=0.

Tools can exploit either of two mechanisms for this purpose\+:

(a) call orte\+\_\+init themselves and utilize the O\+R\+T\+E tool comm library to access the I\+O\+F. This also provides access to other tool library functions -\/ e.\+g., to order that a job be spawned; or

(b) fork/exec the \char`\"{}orte-\/iof\char`\"{} tool and let it serve as the interface to mpirun. This lets the tool avoid calling orte\+\_\+init, and means the tool will not have to compile against the O\+R\+T\+E/\+O\+M\+P\+I libraries. However, the orte-\/iof tool is limited solely to interfacing stdio and cannot be used for other functions included in the tool comm library

Thus, mpirun acts as a \char`\"{}switchyard\char`\"{} for I\+O, taking input from stdin and passing it to rank=0 of the job, and taking stdout/err/diag from all ranks and passing it to its own stdout/err/diag plus any \char`\"{}pull\char`\"{} requestors.

Streams are identified by O\+R\+T\+E process name (to include wildcards, such as \char`\"{}all processes in O\+R\+T\+E job X\char`\"{}) and tag. There are currently only 4 allowed predefined tags\+:


\begin{DoxyItemize}
\item O\+R\+T\+E\+\_\+\+I\+O\+F\+\_\+\+S\+T\+D\+I\+N (value 0)
\item O\+R\+T\+E\+\_\+\+I\+O\+F\+\_\+\+S\+T\+D\+O\+U\+T (value 1)
\item O\+R\+T\+E\+\_\+\+I\+O\+F\+\_\+\+S\+T\+D\+E\+R\+R (value 2)
\item O\+R\+T\+E\+\_\+\+I\+O\+F\+\_\+\+I\+N\+T\+E\+R\+N\+A\+L (value 3)\+: for \char`\"{}internal\char`\"{} messages from the infrastructure, just to differentiate them from user job stdout/stderr
\end{DoxyItemize}

Note that since streams are identified by O\+R\+T\+E process name, the caller has no idea whether the stream is on the local node or a remote node -- it's just a stream.

I\+O\+F components are selected on a \char`\"{}one of many\char`\"{} basis, meaning that only one I\+O\+F component will be selected for a given process. Details for the various components are given in their source code bases.

Each I\+O\+F component must support the following A\+P\+I\+:

push\+: Tie a local file descriptor ({\itshape not} a stream!) to the stdin of the specified process. If the user has not specified that stdin of the specified process is to remain open, this will return an error.

pull\+: Tie a local file descriptor ({\itshape not} a stream!) to a stream. Subsequent input that appears via the stream will automatically be sent to the target file descriptor until the stream is \char`\"{}closed\char`\"{} or an E\+O\+F is received on the local file descriptor. Valid source values include O\+R\+T\+E\+\_\+\+I\+O\+F\+\_\+\+S\+T\+D\+O\+U\+T, O\+R\+T\+E\+\_\+\+I\+O\+F\+\_\+\+S\+T\+D\+E\+R\+R, and O\+R\+T\+E\+\_\+\+I\+O\+F\+\_\+\+I\+N\+T\+E\+R\+N\+A\+L

close\+: Closes a stream, flushing any pending data down it and terminating any \char`\"{}push/pull\char`\"{} connections against it. Unclear yet if this needs to be blocking, or can be done non-\/blocking.

flush\+: Block until all pending data on all open streams has been written down local file descriptors and/or completed sending across the O\+O\+B to remote process targets. 

\subsection{Macro Definition Documentation}
\hypertarget{iof_8h_ad2a1c6c0fe53097c5085653861b90848}{\index{iof.\+h@{iof.\+h}!O\+R\+T\+E\+\_\+\+I\+O\+F\+\_\+\+B\+A\+S\+E\+\_\+\+V\+E\+R\+S\+I\+O\+N\+\_\+2\+\_\+0\+\_\+0@{O\+R\+T\+E\+\_\+\+I\+O\+F\+\_\+\+B\+A\+S\+E\+\_\+\+V\+E\+R\+S\+I\+O\+N\+\_\+2\+\_\+0\+\_\+0}}
\index{O\+R\+T\+E\+\_\+\+I\+O\+F\+\_\+\+B\+A\+S\+E\+\_\+\+V\+E\+R\+S\+I\+O\+N\+\_\+2\+\_\+0\+\_\+0@{O\+R\+T\+E\+\_\+\+I\+O\+F\+\_\+\+B\+A\+S\+E\+\_\+\+V\+E\+R\+S\+I\+O\+N\+\_\+2\+\_\+0\+\_\+0}!iof.\+h@{iof.\+h}}
\subsubsection[{O\+R\+T\+E\+\_\+\+I\+O\+F\+\_\+\+B\+A\+S\+E\+\_\+\+V\+E\+R\+S\+I\+O\+N\+\_\+2\+\_\+0\+\_\+0}]{\setlength{\rightskip}{0pt plus 5cm}\#define O\+R\+T\+E\+\_\+\+I\+O\+F\+\_\+\+B\+A\+S\+E\+\_\+\+V\+E\+R\+S\+I\+O\+N\+\_\+2\+\_\+0\+\_\+0}}\label{iof_8h_ad2a1c6c0fe53097c5085653861b90848}
{\bfseries Value\+:}
\begin{DoxyCode}
MCA\_BASE\_VERSION\_2\_0\_0, \(\backslash\)
  \textcolor{stringliteral}{"iof"}, 2, 0, 0
\end{DoxyCode}


\subsection{Typedef Documentation}
\hypertarget{iof_8h_a3e86e058e0447a72da3ad6e4e47ecc6b}{\index{iof.\+h@{iof.\+h}!orte\+\_\+iof\+\_\+base\+\_\+pull\+\_\+fn\+\_\+t@{orte\+\_\+iof\+\_\+base\+\_\+pull\+\_\+fn\+\_\+t}}
\index{orte\+\_\+iof\+\_\+base\+\_\+pull\+\_\+fn\+\_\+t@{orte\+\_\+iof\+\_\+base\+\_\+pull\+\_\+fn\+\_\+t}!iof.\+h@{iof.\+h}}
\subsubsection[{orte\+\_\+iof\+\_\+base\+\_\+pull\+\_\+fn\+\_\+t}]{\setlength{\rightskip}{0pt plus 5cm}typedef int($\ast$ orte\+\_\+iof\+\_\+base\+\_\+pull\+\_\+fn\+\_\+t)(const {\bf orte\+\_\+process\+\_\+name\+\_\+t} $\ast$peer, orte\+\_\+iof\+\_\+tag\+\_\+t source\+\_\+tag, int fd)}}\label{iof_8h_a3e86e058e0447a72da3ad6e4e47ecc6b}


Explicitly pull data from the specified set of S\+O\+U\+R\+C\+E peers and dump to the indicated output file descriptor. 

Any fragments that arrive on the stream will automatically be written down the fd.


\begin{DoxyParams}{Parameters}
{\em peer} & Name used to qualify set of origin peers. \\
\hline
{\em source\+\_\+tag} & Indicates the output streams to be forwarded \\
\hline
{\em fd} & Local file descriptor for output. \\
\hline
\end{DoxyParams}
\hypertarget{iof_8h_ad0f40f3f458ced4170a896166e0b047f}{\index{iof.\+h@{iof.\+h}!orte\+\_\+iof\+\_\+base\+\_\+push\+\_\+fn\+\_\+t@{orte\+\_\+iof\+\_\+base\+\_\+push\+\_\+fn\+\_\+t}}
\index{orte\+\_\+iof\+\_\+base\+\_\+push\+\_\+fn\+\_\+t@{orte\+\_\+iof\+\_\+base\+\_\+push\+\_\+fn\+\_\+t}!iof.\+h@{iof.\+h}}
\subsubsection[{orte\+\_\+iof\+\_\+base\+\_\+push\+\_\+fn\+\_\+t}]{\setlength{\rightskip}{0pt plus 5cm}typedef int($\ast$ orte\+\_\+iof\+\_\+base\+\_\+push\+\_\+fn\+\_\+t)(const {\bf orte\+\_\+process\+\_\+name\+\_\+t} $\ast$peer, orte\+\_\+iof\+\_\+tag\+\_\+t src\+\_\+tag, int fd)}}\label{iof_8h_ad0f40f3f458ced4170a896166e0b047f}


Explicitly push data from the specified input file descriptor to the stdin of the indicated peer(s). 

The provided peer name can include wildcard values.


\begin{DoxyParams}{Parameters}
{\em peer} & Name of target peer(s) \\
\hline
{\em fd} & Local file descriptor for input. \\
\hline
\end{DoxyParams}
