<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta name="generator" content="AsciiDoc 8.6.8">
<title>MLtonProcess</title>
<link rel="stylesheet" href="./asciidoc.css" type="text/css">
<link rel="stylesheet" href="./pygments.css" type="text/css">


<script type="text/javascript" src="./asciidoc.js"></script>
<script type="text/javascript">
/*<![CDATA[*/
asciidoc.install();
/*]]>*/
</script>
<link rel="stylesheet" href="./mlton.css" type="text/css"/>
</head>
<body class="article">
<div id="banner">
<div id="banner-home">
<a href="./Home">MLton 20130715</a>
</div>
</div>
<div id="header">
<h1>MLtonProcess</h1>
</div>
<div id="content">
<div id="preamble">
<div class="sectionbody">
<div class="listingblock">
<div class="content"><div class="highlight"><pre><span class="k">signature</span><span class="w"> </span><span class="n">MLTON_PROCESS</span><span class="w"> </span><span class="p">=</span><span class="w"></span>
<span class="w">   </span><span class="k">sig</span><span class="w"></span>
<span class="w">      </span><span class="k">type</span><span class="w"> </span><span class="n">pid</span><span class="w"></span>

<span class="w">      </span><span class="k">val</span><span class="w"> </span><span class="n">spawn</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="n">args</span><span class="p">:</span><span class="w"> </span><span class="n">string</span><span class="w"> </span><span class="n">list</span><span class="p">,</span><span class="w"> </span><span class="n">path</span><span class="p">:</span><span class="w"> </span><span class="n">string</span><span class="p">}</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="n">pid</span><span class="w"></span>
<span class="w">      </span><span class="k">val</span><span class="w"> </span><span class="n">spawne</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="n">args</span><span class="p">:</span><span class="w"> </span><span class="n">string</span><span class="w"> </span><span class="n">list</span><span class="p">,</span><span class="w"> </span><span class="n">env</span><span class="p">:</span><span class="w"> </span><span class="n">string</span><span class="w"> </span><span class="n">list</span><span class="p">,</span><span class="w"> </span><span class="n">path</span><span class="p">:</span><span class="w"> </span><span class="n">string</span><span class="p">}</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="n">pid</span><span class="w"></span>
<span class="w">      </span><span class="k">val</span><span class="w"> </span><span class="n">spawnp</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="n">args</span><span class="p">:</span><span class="w"> </span><span class="n">string</span><span class="w"> </span><span class="n">list</span><span class="p">,</span><span class="w"> </span><span class="n">file</span><span class="p">:</span><span class="w"> </span><span class="n">string</span><span class="p">}</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="n">pid</span><span class="w"></span>

<span class="w">      </span><span class="k">type</span><span class="w"> </span><span class="p">(</span><span class="n">&#39;stdin</span><span class="p">,</span><span class="w"> </span><span class="n">&#39;stdout</span><span class="p">,</span><span class="w"> </span><span class="n">&#39;stderr</span><span class="p">)</span><span class="w"> </span><span class="n">t</span><span class="w"></span>

<span class="w">      </span><span class="k">type</span><span class="w"> </span><span class="n">input</span><span class="w"></span>
<span class="w">      </span><span class="k">type</span><span class="w"> </span><span class="n">output</span><span class="w"></span>

<span class="w">      </span><span class="k">type</span><span class="w"> </span><span class="n">none</span><span class="w"></span>
<span class="w">      </span><span class="k">type</span><span class="w"> </span><span class="n">chain</span><span class="w"></span>
<span class="w">      </span><span class="k">type</span><span class="w"> </span><span class="n">any</span><span class="w"></span>

<span class="w">      </span><span class="k">exception</span><span class="w"> </span><span class="n">MisuseOfForget</span><span class="w"></span>
<span class="w">      </span><span class="k">exception</span><span class="w"> </span><span class="n">DoublyRedirected</span><span class="w"></span>

<span class="w">      </span><span class="k">structure</span><span class="w"> </span><span class="n">Child</span><span class="p">:</span><span class="w"></span>
<span class="w">        </span><span class="k">sig</span><span class="w"></span>
<span class="w">          </span><span class="k">type</span><span class="w"> </span><span class="p">(</span><span class="n">&#39;use</span><span class="p">,</span><span class="w"> </span><span class="n">&#39;dir</span><span class="p">)</span><span class="w"> </span><span class="n">t</span><span class="w"></span>

<span class="w">          </span><span class="k">val</span><span class="w"> </span><span class="n">binIn</span><span class="p">:</span><span class="w"> </span><span class="p">(</span><span class="n">BinIO</span><span class="p">.</span><span class="n">instream</span><span class="p">,</span><span class="w"> </span><span class="n">input</span><span class="p">)</span><span class="w"> </span><span class="n">t</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="n">BinIO</span><span class="p">.</span><span class="n">instream</span><span class="w"></span>
<span class="w">          </span><span class="k">val</span><span class="w"> </span><span class="n">binOut</span><span class="p">:</span><span class="w"> </span><span class="p">(</span><span class="n">BinIO</span><span class="p">.</span><span class="n">outstream</span><span class="p">,</span><span class="w"> </span><span class="n">output</span><span class="p">)</span><span class="w"> </span><span class="n">t</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="n">BinIO</span><span class="p">.</span><span class="n">outstream</span><span class="w"></span>
<span class="w">          </span><span class="k">val</span><span class="w"> </span><span class="n">fd</span><span class="p">:</span><span class="w"> </span><span class="p">(</span><span class="n">Posix</span><span class="p">.</span><span class="n">FileSys</span><span class="p">.</span><span class="n">file_desc</span><span class="p">,</span><span class="w"> </span><span class="n">&#39;dir</span><span class="p">)</span><span class="w"> </span><span class="n">t</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="n">Posix</span><span class="p">.</span><span class="n">FileSys</span><span class="p">.</span><span class="n">file_desc</span><span class="w"></span>
<span class="w">          </span><span class="k">val</span><span class="w"> </span><span class="n">remember</span><span class="p">:</span><span class="w"> </span><span class="p">(</span><span class="n">any</span><span class="p">,</span><span class="w"> </span><span class="n">&#39;dir</span><span class="p">)</span><span class="w"> </span><span class="n">t</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="p">(</span><span class="n">&#39;use</span><span class="p">,</span><span class="w"> </span><span class="n">&#39;dir</span><span class="p">)</span><span class="w"> </span><span class="n">t</span><span class="w"></span>
<span class="w">          </span><span class="k">val</span><span class="w"> </span><span class="n">textIn</span><span class="p">:</span><span class="w"> </span><span class="p">(</span><span class="n">TextIO</span><span class="p">.</span><span class="n">instream</span><span class="p">,</span><span class="w"> </span><span class="n">input</span><span class="p">)</span><span class="w"> </span><span class="n">t</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="n">TextIO</span><span class="p">.</span><span class="n">instream</span><span class="w"></span>
<span class="w">          </span><span class="k">val</span><span class="w"> </span><span class="n">textOut</span><span class="p">:</span><span class="w"> </span><span class="p">(</span><span class="n">TextIO</span><span class="p">.</span><span class="n">outstream</span><span class="p">,</span><span class="w"> </span><span class="n">output</span><span class="p">)</span><span class="w"> </span><span class="n">t</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="n">TextIO</span><span class="p">.</span><span class="n">outstream</span><span class="w"></span>
<span class="w">        </span><span class="k">end</span><span class="w"></span>

<span class="w">      </span><span class="k">structure</span><span class="w"> </span><span class="n">Param</span><span class="p">:</span><span class="w"></span>
<span class="w">        </span><span class="k">sig</span><span class="w"></span>
<span class="w">          </span><span class="k">type</span><span class="w"> </span><span class="p">(</span><span class="n">&#39;use</span><span class="p">,</span><span class="w"> </span><span class="n">&#39;dir</span><span class="p">)</span><span class="w"> </span><span class="n">t</span><span class="w"></span>

<span class="w">          </span><span class="k">val</span><span class="w"> </span><span class="n">child</span><span class="p">:</span><span class="w"> </span><span class="p">(</span><span class="n">chain</span><span class="p">,</span><span class="w"> </span><span class="n">&#39;dir</span><span class="p">)</span><span class="w"> </span><span class="n">Child</span><span class="p">.</span><span class="n">t</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="p">(</span><span class="n">none</span><span class="p">,</span><span class="w"> </span><span class="n">&#39;dir</span><span class="p">)</span><span class="w"> </span><span class="n">t</span><span class="w"></span>
<span class="w">          </span><span class="k">val</span><span class="w"> </span><span class="n">fd</span><span class="p">:</span><span class="w"> </span><span class="n">Posix</span><span class="p">.</span><span class="n">FileSys</span><span class="p">.</span><span class="n">file_desc</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="p">(</span><span class="n">none</span><span class="p">,</span><span class="w"> </span><span class="n">&#39;dir</span><span class="p">)</span><span class="w"> </span><span class="n">t</span><span class="w"></span>
<span class="w">          </span><span class="k">val</span><span class="w"> </span><span class="n">file</span><span class="p">:</span><span class="w"> </span><span class="n">string</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="p">(</span><span class="n">none</span><span class="p">,</span><span class="w"> </span><span class="n">&#39;dir</span><span class="p">)</span><span class="w"> </span><span class="n">t</span><span class="w"></span>
<span class="w">          </span><span class="k">val</span><span class="w"> </span><span class="n">forget</span><span class="p">:</span><span class="w"> </span><span class="p">(</span><span class="n">&#39;use</span><span class="p">,</span><span class="w"> </span><span class="n">&#39;dir</span><span class="p">)</span><span class="w"> </span><span class="n">t</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="p">(</span><span class="n">any</span><span class="p">,</span><span class="w"> </span><span class="n">&#39;dir</span><span class="p">)</span><span class="w"> </span><span class="n">t</span><span class="w"></span>
<span class="w">          </span><span class="k">val</span><span class="w"> </span><span class="n">null</span><span class="p">:</span><span class="w"> </span><span class="p">(</span><span class="n">none</span><span class="p">,</span><span class="w"> </span><span class="n">&#39;dir</span><span class="p">)</span><span class="w"> </span><span class="n">t</span><span class="w"></span>
<span class="w">          </span><span class="k">val</span><span class="w"> </span><span class="n">pipe</span><span class="p">:</span><span class="w"> </span><span class="p">(</span><span class="n">&#39;use</span><span class="p">,</span><span class="w"> </span><span class="n">&#39;dir</span><span class="p">)</span><span class="w"> </span><span class="n">t</span><span class="w"></span>
<span class="w">          </span><span class="k">val</span><span class="w"> </span><span class="n">self</span><span class="p">:</span><span class="w"> </span><span class="p">(</span><span class="n">none</span><span class="p">,</span><span class="w"> </span><span class="n">&#39;dir</span><span class="p">)</span><span class="w"> </span><span class="n">t</span><span class="w"></span>
<span class="w">        </span><span class="k">end</span><span class="w"></span>

<span class="w">      </span><span class="k">val</span><span class="w"> </span><span class="n">create</span><span class="p">:</span><span class="w"></span>
<span class="w">         </span><span class="p">{</span><span class="n">args</span><span class="p">:</span><span class="w"> </span><span class="n">string</span><span class="w"> </span><span class="n">list</span><span class="p">,</span><span class="w"></span>
<span class="w">          </span><span class="n">env</span><span class="p">:</span><span class="w"> </span><span class="n">string</span><span class="w"> </span><span class="n">list</span><span class="w"> </span><span class="n">option</span><span class="p">,</span><span class="w"></span>
<span class="w">          </span><span class="n">path</span><span class="p">:</span><span class="w"> </span><span class="n">string</span><span class="p">,</span><span class="w"></span>
<span class="w">          </span><span class="n">stderr</span><span class="p">:</span><span class="w"> </span><span class="p">(</span><span class="n">&#39;stderr</span><span class="p">,</span><span class="w"> </span><span class="n">output</span><span class="p">)</span><span class="w"> </span><span class="n">Param</span><span class="p">.</span><span class="n">t</span><span class="p">,</span><span class="w"></span>
<span class="w">          </span><span class="n">stdin</span><span class="p">:</span><span class="w"> </span><span class="p">(</span><span class="n">&#39;stdin</span><span class="p">,</span><span class="w"> </span><span class="n">input</span><span class="p">)</span><span class="w"> </span><span class="n">Param</span><span class="p">.</span><span class="n">t</span><span class="p">,</span><span class="w"></span>
<span class="w">          </span><span class="n">stdout</span><span class="p">:</span><span class="w"> </span><span class="p">(</span><span class="n">&#39;stdout</span><span class="p">,</span><span class="w"> </span><span class="n">output</span><span class="p">)</span><span class="w"> </span><span class="n">Param</span><span class="p">.</span><span class="n">t</span><span class="p">}</span><span class="w"></span>
<span class="w">         </span><span class="p">-&gt;</span><span class="w"> </span><span class="p">(</span><span class="n">&#39;stdin</span><span class="p">,</span><span class="w"> </span><span class="n">&#39;stdout</span><span class="p">,</span><span class="w"> </span><span class="n">&#39;stderr</span><span class="p">)</span><span class="w"> </span><span class="n">t</span><span class="w"></span>
<span class="w">      </span><span class="k">val</span><span class="w"> </span><span class="n">getStderr</span><span class="p">:</span><span class="w"> </span><span class="p">(</span><span class="n">&#39;stdin</span><span class="p">,</span><span class="w"> </span><span class="n">&#39;stdout</span><span class="p">,</span><span class="w"> </span><span class="n">&#39;stderr</span><span class="p">)</span><span class="w"> </span><span class="n">t</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="p">(</span><span class="n">&#39;stderr</span><span class="p">,</span><span class="w"> </span><span class="n">input</span><span class="p">)</span><span class="w"> </span><span class="n">Child</span><span class="p">.</span><span class="n">t</span><span class="w"></span>
<span class="w">      </span><span class="k">val</span><span class="w"> </span><span class="n">getStdin</span><span class="p">:</span><span class="w">  </span><span class="p">(</span><span class="n">&#39;stdin</span><span class="p">,</span><span class="w"> </span><span class="n">&#39;stdout</span><span class="p">,</span><span class="w"> </span><span class="n">&#39;stderr</span><span class="p">)</span><span class="w"> </span><span class="n">t</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="p">(</span><span class="n">&#39;stdin</span><span class="p">,</span><span class="w"> </span><span class="n">output</span><span class="p">)</span><span class="w"> </span><span class="n">Child</span><span class="p">.</span><span class="n">t</span><span class="w"></span>
<span class="w">      </span><span class="k">val</span><span class="w"> </span><span class="n">getStdout</span><span class="p">:</span><span class="w"> </span><span class="p">(</span><span class="n">&#39;stdin</span><span class="p">,</span><span class="w"> </span><span class="n">&#39;stdout</span><span class="p">,</span><span class="w"> </span><span class="n">&#39;stderr</span><span class="p">)</span><span class="w"> </span><span class="n">t</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="p">(</span><span class="n">&#39;stdout</span><span class="p">,</span><span class="w"> </span><span class="n">input</span><span class="p">)</span><span class="w"> </span><span class="n">Child</span><span class="p">.</span><span class="n">t</span><span class="w"></span>
<span class="w">      </span><span class="k">val</span><span class="w"> </span><span class="n">kill</span><span class="p">:</span><span class="w"> </span><span class="p">(</span><span class="n">&#39;stdin</span><span class="p">,</span><span class="w"> </span><span class="n">&#39;stdout</span><span class="p">,</span><span class="w"> </span><span class="n">&#39;stderr</span><span class="p">)</span><span class="w"> </span><span class="n">t</span><span class="w"> </span><span class="n">*</span><span class="w"> </span><span class="n">Posix</span><span class="p">.</span><span class="n">Signal</span><span class="p">.</span><span class="n">signal</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="n">unit</span><span class="w"></span>
<span class="w">      </span><span class="k">val</span><span class="w"> </span><span class="n">reap</span><span class="p">:</span><span class="w"> </span><span class="p">(</span><span class="n">&#39;stdin</span><span class="p">,</span><span class="w"> </span><span class="n">&#39;stdout</span><span class="p">,</span><span class="w"> </span><span class="n">&#39;stderr</span><span class="p">)</span><span class="w"> </span><span class="n">t</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="n">Posix</span><span class="p">.</span><span class="n">Process</span><span class="p">.</span><span class="n">exit_status</span><span class="w"></span>
<span class="w">   </span><span class="k">end</span><span class="w"></span>
</pre></div></div></div>
</div>
</div>
<div class="sect1">
<h2 id="_spawn">Spawn</h2>
<div class="sectionbody">
<div class="paragraph"><p>The <span class="monospaced">spawn</span> functions provide an alternative to the
<span class="monospaced">fork</span>/<span class="monospaced">exec</span> idiom that is typically used to create a new
process.  On most platforms, the <span class="monospaced">spawn</span> functions are simple
wrappers around <span class="monospaced">fork</span>/<span class="monospaced">exec</span>.  However, under Windows, the
<span class="monospaced">spawn</span> functions are primitive.  All <span class="monospaced">spawn</span> functions return
the process id of the spawned process.  They differ in how the
executable is found and the environment that it uses.</p></div>
<div class="ulist"><ul>
<li>
<p>
<span class="monospaced">spawn {args, path}</span>
</p>
<div class="paragraph"><p>starts a new process running the executable specified by <span class="monospaced">path</span>
with the arguments <span class="monospaced">args</span>.  Like <span class="monospaced">Posix.Process.exec</span>.</p></div>
</li>
<li>
<p>
<span class="monospaced">spawne {args, env, path}</span>
</p>
<div class="paragraph"><p>starts a new process running the executable specified by <span class="monospaced">path</span> with
the arguments <span class="monospaced">args</span> and environment <span class="monospaced">env</span>.  Like
<span class="monospaced">Posix.Process.exece</span>.</p></div>
</li>
<li>
<p>
<span class="monospaced">spawnp {args, file}</span>
</p>
<div class="paragraph"><p>search the <span class="monospaced">PATH</span> environment variable for an executable named <span class="monospaced">file</span>,
and start a new process running that executable with the arguments
<span class="monospaced">args</span>.  Like <span class="monospaced">Posix.Process.execp</span>.</p></div>
</li>
</ul></div>
</div>
</div>
<div class="sect1">
<h2 id="_create">Create</h2>
<div class="sectionbody">
<div class="paragraph"><p><span class="monospaced">MLton.Process.create</span> provides functionality similar to
<span class="monospaced">Unix.executeInEnv</span>, but provides more control control over the input,
output, and error streams.  In addition, <span class="monospaced">create</span> works on all
platforms, including Cygwin and MinGW (Windows) where <span class="monospaced">Posix.fork</span> is
unavailable.  For greatest portability programs should still use the
standard <span class="monospaced">Unix.execute</span>, <span class="monospaced">Unix.executeInEnv</span>, and <span class="monospaced">OS.Process.system</span>.</p></div>
<div class="paragraph"><p>The following types and sub-structures are used by the <span class="monospaced">create</span>
function.  They provide static type checking of correct stream usage.</p></div>
<div class="sect2">
<h3 id="_child">Child</h3>
<div class="ulist"><ul>
<li>
<p>
<span class="monospaced">('use, 'dir) Child.t</span>
</p>
<div class="paragraph"><p>This represents a handle to one of a child&#8217;s standard streams. The
<span class="monospaced">'dir</span> is viewed with respect to the parent. Thus a <span class="monospaced">('a, input)
Child.t</span> handle means that the parent may input the output from the
child.</p></div>
</li>
<li>
<p>
<span class="monospaced">Child.{bin,text}{In,Out} h</span>
</p>
<div class="paragraph"><p>These functions take a handle and bind it to a stream of the named
type.  The type system will detect attempts to reverse the direction
of a stream or to use the same stream in multiple, incompatible ways.</p></div>
</li>
<li>
<p>
<span class="monospaced">Child.fd h</span>
</p>
<div class="paragraph"><p>This function behaves like the other <span class="monospaced">Child.*</span> functions; it opens a
stream. However, it does not enforce that you read or write from the
handle. If you use the descriptor in an inappropriate direction, the
behavior is undefined. Furthermore, this function may potentially be
unavailable on future MLton host platforms.</p></div>
</li>
<li>
<p>
<span class="monospaced">Child.remember h</span>
</p>
<div class="paragraph"><p>This function takes a stream of use <span class="monospaced">any</span> and resets the use of the
stream so that the stream may be used by <span class="monospaced">Child.*</span>. An <span class="monospaced">any</span> stream
may have had use <span class="monospaced">none</span> or <span class="monospaced">'use</span> prior to calling <span class="monospaced">Param.forget</span>. If
the stream was <span class="monospaced">none</span> and is used, <span class="monospaced">MisuseOfForget</span> is raised.</p></div>
</li>
</ul></div>
</div>
<div class="sect2">
<h3 id="_param">Param</h3>
<div class="ulist"><ul>
<li>
<p>
<span class="monospaced">('use, 'dir) Param.t</span>
</p>
<div class="paragraph"><p>This is a handle to an input/output source and will be passed to the
created child process. The <span class="monospaced">'dir</span> is relative to the child process.
Input means that the child process will read from this stream.</p></div>
</li>
<li>
<p>
<span class="monospaced">Param.child h</span>
</p>
<div class="paragraph"><p>Connect the stream of the new child process to the stream of a
previously created child process. A single child stream should be
connected to only one child process or else <span class="monospaced">DoublyRedirected</span> will be
raised.</p></div>
</li>
<li>
<p>
<span class="monospaced">Param.fd fd</span>
</p>
<div class="paragraph"><p>This creates a stream from the provided file descriptor which will be
closed when <span class="monospaced">create</span> is called. This function may not be available on
future MLton host platforms.</p></div>
</li>
<li>
<p>
<span class="monospaced">Param.forget h</span>
</p>
<div class="paragraph"><p>This hides the type of the actual parameter as <span class="monospaced">any</span>. This is useful
if you are implementing an application which conditionally attaches
the child process to files or pipes. However, you must ensure that
your use after <span class="monospaced">Child.remember</span> matches the original type.</p></div>
</li>
<li>
<p>
<span class="monospaced">Param.file s</span>
</p>
<div class="paragraph"><p>Open the given file and connect it to the child process. Note that the
file will be opened only when <span class="monospaced">create</span> is called. So any exceptions
will be raised there and not by this function. If used for <span class="monospaced">input</span>,
the file is opened read-only. If used for <span class="monospaced">output</span>, the file is opened
read-write.</p></div>
</li>
<li>
<p>
<span class="monospaced">Param.null</span>
</p>
<div class="paragraph"><p>In some situations, the child process should have its output
discarded.  The <span class="monospaced">null</span> param when passed as <span class="monospaced">stdout</span> or <span class="monospaced">stderr</span> does
this.  When used for <span class="monospaced">stdin</span>, the child process will either receive
<span class="monospaced">EOF</span> or a failure condition if it attempts to read from <span class="monospaced">stdin</span>.</p></div>
</li>
<li>
<p>
<span class="monospaced">Param.pipe</span>
</p>
<div class="paragraph"><p>This will connect the input/output of the child process to a pipe
which the parent process holds. This may later form the input to one
of the <span class="monospaced">Child.*</span> functions and/or the <span class="monospaced">Param.child</span> function.</p></div>
</li>
<li>
<p>
<span class="monospaced">Param.self</span>
</p>
<div class="paragraph"><p>This will connect the input/output of the child process to the
corresponding stream of the parent process.</p></div>
</li>
</ul></div>
</div>
<div class="sect2">
<h3 id="_process">Process</h3>
<div class="ulist"><ul>
<li>
<p>
<span class="monospaced">type ('stdin, 'stdout, 'stderr) t</span>
</p>
<div class="paragraph"><p>represents a handle to a child process.  The type arguments capture
how the named stream of the child process may be used.</p></div>
</li>
<li>
<p>
<span class="monospaced">type any</span>
</p>
<div class="paragraph"><p>bypasses the type system in situations where an application does not
want the it to enforce correct usage.  See <span class="monospaced">Child.remember</span> and
<span class="monospaced">Param.forget</span>.</p></div>
</li>
<li>
<p>
<span class="monospaced">type chain</span>
</p>
<div class="paragraph"><p>means that the child process&#8217;s stream was connected via a pipe to the
parent process. The parent process may pass this pipe in turn to
another child, thus chaining them together.</p></div>
</li>
<li>
<p>
<span class="monospaced">type input, output</span>
</p>
<div class="paragraph"><p>record the direction that a stream flows.  They are used as a part of
<span class="monospaced">Param.t</span> and <span class="monospaced">Child.t</span> and is detailed there.</p></div>
</li>
<li>
<p>
<span class="monospaced">type none</span>
</p>
<div class="paragraph"><p>means that the child process&#8217;s stream my not be used by the parent
process.  This happens when the child process is connected directly to
some source.</p></div>
<div class="paragraph"><p>The types <span class="monospaced">BinIO.instream</span>, <span class="monospaced">BinIO.outstream</span>, <span class="monospaced">TextIO.instream</span>,
<span class="monospaced">TextIO.outstream</span>, and <span class="monospaced">Posix.FileSys.file_desc</span> are also valid types
with which to instantiate child streams.</p></div>
</li>
<li>
<p>
<span class="monospaced">exception MisuseOfForget</span>
</p>
<div class="paragraph"><p>may be raised if <span class="monospaced">Child.remember</span> and <span class="monospaced">Param.forget</span> are used to
bypass the normal type checking.  This exception will only be raised
in cases where the <span class="monospaced">forget</span> mechanism allows a misuse that would be
impossible with the type-safe versions.</p></div>
</li>
<li>
<p>
<span class="monospaced">exception DoublyRedirected</span>
</p>
<div class="paragraph"><p>raised if a stream connected to a child process is redirected to two
separate child processes.  It is safe, though bad style, to use the a
<span class="monospaced">Child.t</span> with the same <span class="monospaced">Child.*</span> function repeatedly.</p></div>
</li>
<li>
<p>
<span class="monospaced">create {args, path, env, stderr, stdin, stdout}</span>
</p>
<div class="paragraph"><p>starts a child process with the given command-line <span class="monospaced">args</span> (excluding
the program name). <span class="monospaced">path</span> should be an absolute path to the executable
run in the new child process; relative paths work, but are less
robust.  Optionally, the environment may be overridden with <span class="monospaced">env</span>
where each string element has the form <span class="monospaced">"key=value"</span>. The <span class="monospaced">std*</span>
options must be provided by the <span class="monospaced">Param.*</span> functions documented above.</p></div>
<div class="paragraph"><p>Processes which are <span class="monospaced">create</span>-d must be either <span class="monospaced">reap</span>-ed or <span class="monospaced">kill</span>-ed.</p></div>
</li>
<li>
<p>
<span class="monospaced">getStd{in,out,err} proc</span>
</p>
<div class="paragraph"><p>gets a handle to the specified stream. These should be used by the
<span class="monospaced">Child.*</span> functions. Failure to use a stream connected via pipe to a
child process may result in runtime dead-lock and elicits a compiler
warning.</p></div>
</li>
<li>
<p>
<span class="monospaced">kill (proc, sig)</span>
</p>
<div class="paragraph"><p>terminates the child process immediately.  The signal may or may not
mean anything depending on the host platform.  A good value is
<span class="monospaced">Posix.Signal.term</span>.</p></div>
</li>
<li>
<p>
<span class="monospaced">reap proc</span>
</p>
<div class="paragraph"><p>waits for the child process to terminate and return its exit status.</p></div>
</li>
</ul></div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_important_usage_notes">Important usage notes</h2>
<div class="sectionbody">
<div class="paragraph"><p>When building an application with many pipes between child processes,
it is important to ensure that there are no cycles in the undirected
pipe graph.  If this property is not maintained, deadlocks are a very
serious potential bug which may only appear under difficult to
reproduce conditions.</p></div>
<div class="paragraph"><p>The danger lies in that most operating systems implement pipes with a
fixed buffer size. If process A has two output pipes which process B
reads, it can happen that process A blocks writing to pipe 2 because
it is full while process B blocks reading from pipe 1 because it is
empty. This same situation can happen with any undirected cycle formed
between processes (vertexes) and pipes (undirected edges) in the
graph.</p></div>
<div class="paragraph"><p>It is possible to make this safe using low-level I/O primitives for
polling.  However, these primitives are not very portable and
difficult to use properly.  A far better approach is to make sure you
never create a cycle in the first place.</p></div>
<div class="paragraph"><p>For these reasons, the <span class="monospaced">Unix.executeInEnv</span> is a very dangerous
function. Be careful when using it to ensure that the child process
only operates on either <span class="monospaced">stdin</span> or <span class="monospaced">stdout</span>, but not both.</p></div>
</div>
</div>
<div class="sect1">
<h2 id="_example_use_of_mlton_process_create">Example use of MLton.Process.create</h2>
<div class="sectionbody">
<div class="paragraph"><p>The following example program launches the <span class="monospaced">ipconfig</span> utility, pipes
its output through <span class="monospaced">grep</span>, and then reads the result back into the
program.</p></div>
<div class="listingblock">
<div class="content"><div class="highlight"><pre><span class="k">open</span><span class="w"> </span><span class="n">MLton</span><span class="p">.</span><span class="n">Process</span><span class="w"></span>
<span class="k">val</span><span class="w"> </span><span class="n">p</span><span class="w"> </span><span class="p">=</span><span class="w"></span>
<span class="w">        </span><span class="n">create</span><span class="w"> </span><span class="p">{</span><span class="n">args</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">[</span><span class="w"> </span><span class="s">&quot;/all&quot;</span><span class="w"> </span><span class="p">],</span><span class="w"></span>
<span class="w">                </span><span class="n">env</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">NONE</span><span class="p">,</span><span class="w"></span>
<span class="w">                </span><span class="n">path</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="s">&quot;C:</span><span class="se">\\</span><span class="s">WINDOWS</span><span class="se">\\</span><span class="s">system32</span><span class="se">\\</span><span class="s">ipconfig.exe&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w">                </span><span class="n">stderr</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">Param</span><span class="p">.</span><span class="n">self</span><span class="p">,</span><span class="w"></span>
<span class="w">                </span><span class="n">stdin</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">Param</span><span class="p">.</span><span class="n">null</span><span class="p">,</span><span class="w"></span>
<span class="w">                </span><span class="n">stdout</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">Param</span><span class="p">.</span><span class="n">pipe</span><span class="p">}</span><span class="w"></span>
<span class="k">val</span><span class="w"> </span><span class="n">q</span><span class="w"> </span><span class="p">=</span><span class="w"></span>
<span class="w">        </span><span class="n">create</span><span class="w"> </span><span class="p">{</span><span class="n">args</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">[</span><span class="w"> </span><span class="s">&quot;IP-Ad&quot;</span><span class="w"> </span><span class="p">],</span><span class="w"></span>
<span class="w">                </span><span class="n">env</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">NONE</span><span class="p">,</span><span class="w"></span>
<span class="w">                </span><span class="n">path</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="s">&quot;C:</span><span class="se">\\</span><span class="s">msys</span><span class="se">\\</span><span class="s">bin</span><span class="se">\\</span><span class="s">grep.exe&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w">                </span><span class="n">stderr</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">Param</span><span class="p">.</span><span class="n">self</span><span class="p">,</span><span class="w"></span>
<span class="w">                </span><span class="n">stdin</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">Param</span><span class="p">.</span><span class="n">child</span><span class="w"> </span><span class="p">(</span><span class="n">getStdout</span><span class="w"> </span><span class="n">p</span><span class="p">),</span><span class="w"></span>
<span class="w">                </span><span class="n">stdout</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">Param</span><span class="p">.</span><span class="n">pipe</span><span class="p">}</span><span class="w"></span>
<span class="k">fun</span><span class="w"> </span><span class="n">suck</span><span class="w"> </span><span class="n">h</span><span class="w"> </span><span class="p">=</span><span class="w"></span>
<span class="w">        </span><span class="k">case</span><span class="w"> </span><span class="n">TextIO</span><span class="p">.</span><span class="n">inputLine</span><span class="w"> </span><span class="n">h</span><span class="w"> </span><span class="k">of</span><span class="w"></span>
<span class="w">                </span><span class="n">NONE</span><span class="w"> </span><span class="p">=&gt;</span><span class="w"> </span><span class="p">()</span><span class="w"></span>
<span class="w">                </span><span class="p">|</span><span class="w"> </span><span class="n">SOME</span><span class="w"> </span><span class="n">s</span><span class="w"> </span><span class="p">=&gt;</span><span class="w"> </span><span class="p">(</span><span class="n">print</span><span class="w"> </span><span class="p">(</span><span class="s">&quot;&#39;&quot;</span><span class="w"> </span><span class="n">^</span><span class="w"> </span><span class="n">s</span><span class="w"> </span><span class="n">^</span><span class="w"> </span><span class="s">&quot;&#39;</span><span class="se">\n</span><span class="s">&quot;</span><span class="p">);</span><span class="w"> </span><span class="n">suck</span><span class="w"> </span><span class="n">h</span><span class="p">)</span><span class="w"></span>

<span class="k">val</span><span class="w"> </span><span class="p">()</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">suck</span><span class="w"> </span><span class="p">(</span><span class="n">Child</span><span class="p">.</span><span class="n">textIn</span><span class="w"> </span><span class="p">(</span><span class="n">getStdout</span><span class="w"> </span><span class="n">q</span><span class="p">))</span><span class="w"></span>
</pre></div></div></div>
</div>
</div>
</div>
<div id="footnotes"><hr></div>
<div id="footer">
<div id="footer-text">
</div>
<div id="footer-badges">
</div>
</div>
</body>
</html>
