[hcoop/debian/mlton.git] / doc / guide / localhost / MLtonProcess

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