doc/guide/localhost/MLtonProcess

   1 <!DOCTYPE html>
   2 <html lang="en">
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5 <meta name="generator" content="AsciiDoc 8.6.9">
   6 <title>MLtonProcess</title>
   7 <link rel="stylesheet" href="./asciidoc.css" type="text/css">
   8 <link rel="stylesheet" href="./pygments.css" type="text/css">
   9
  10
  11 <script type="text/javascript" src="./asciidoc.js"></script>
  12 <script type="text/javascript">
  13 /*<![CDATA[*/
  14 asciidoc.install();
  15 /*]]>*/
  16 </script>
  17 <link rel="stylesheet" href="./mlton.css" type="text/css">
  18 </head>
  19 <body class="article">
  20 <div id="banner">
  21 <div id="banner-home">
  22 <a href="./Home">MLton 20180207</a>
  23 </div>
  24 </div>
  25 <div id="header">
  26 <h1>MLtonProcess</h1>
  27 </div>
  28 <div id="content">
  29 <div id="preamble">
  30 <div class="sectionbody">
  31 <div class="listingblock">
  32 <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>
  33 <span class="w">   </span><span class="k">sig</span><span class="w"></span>
  34 <span class="w">      </span><span class="k">type</span><span class="w"> </span><span class="n">pid</span><span class="w"></span>
  35
  36 <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>
  37 <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>
  38 <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>
  39
  40 <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>
  41
  42 <span class="w">      </span><span class="k">type</span><span class="w"> </span><span class="n">input</span><span class="w"></span>
  43 <span class="w">      </span><span class="k">type</span><span class="w"> </span><span class="n">output</span><span class="w"></span>
  44
  45 <span class="w">      </span><span class="k">type</span><span class="w"> </span><span class="n">none</span><span class="w"></span>
  46 <span class="w">      </span><span class="k">type</span><span class="w"> </span><span class="n">chain</span><span class="w"></span>
  47 <span class="w">      </span><span class="k">type</span><span class="w"> </span><span class="n">any</span><span class="w"></span>
  48
  49 <span class="w">      </span><span class="k">exception</span><span class="w"> </span><span class="n">MisuseOfForget</span><span class="w"></span>
  50 <span class="w">      </span><span class="k">exception</span><span class="w"> </span><span class="n">DoublyRedirected</span><span class="w"></span>
  51
  52 <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>
  53 <span class="w">        </span><span class="k">sig</span><span class="w"></span>
  54 <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>
  55
  56 <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>
  57 <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>
  58 <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>
  59 <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>
  60 <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>
  61 <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>
  62 <span class="w">        </span><span class="k">end</span><span class="w"></span>
  63
  64 <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>
  65 <span class="w">        </span><span class="k">sig</span><span class="w"></span>
  66 <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>
  67
  68 <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>
  69 <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>
  70 <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>
  71 <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>
  72 <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>
  73 <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>
  74 <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>
  75 <span class="w">        </span><span class="k">end</span><span class="w"></span>
  76
  77 <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>
  78 <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>
  79 <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>
  80 <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>
  81 <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>
  82 <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>
  83 <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>
  84 <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>
  85 <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>
  86 <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>
  87 <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>
  88 <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>
  89 <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>
  90 <span class="w">   </span><span class="k">end</span><span class="w"></span>
  91 </pre></div></div></div>
  92 </div>
  93 </div>
  94 <div class="sect1">
  95 <h2 id="_spawn">Spawn</h2>
  96 <div class="sectionbody">
  97 <div class="paragraph"><p>The <span class="monospaced">spawn</span> functions provide an alternative to the
  98 <span class="monospaced">fork</span>/<span class="monospaced">exec</span> idiom that is typically used to create a new
  99 process.  On most platforms, the <span class="monospaced">spawn</span> functions are simple
 100 wrappers around <span class="monospaced">fork</span>/<span class="monospaced">exec</span>.  However, under Windows, the
 101 <span class="monospaced">spawn</span> functions are primitive.  All <span class="monospaced">spawn</span> functions return
 102 the process id of the spawned process.  They differ in how the
 103 executable is found and the environment that it uses.</p></div>
 104 <div class="ulist"><ul>
 105 <li>
 106 <p>
 107 <span class="monospaced">spawn {args, path}</span>
 108 </p>
 109 <div class="paragraph"><p>starts a new process running the executable specified by <span class="monospaced">path</span>
 110 with the arguments <span class="monospaced">args</span>.  Like <span class="monospaced">Posix.Process.exec</span>.</p></div>
 111 </li>
 112 <li>
 113 <p>
 114 <span class="monospaced">spawne {args, env, path}</span>
 115 </p>
 116 <div class="paragraph"><p>starts a new process running the executable specified by <span class="monospaced">path</span> with
 117 the arguments <span class="monospaced">args</span> and environment <span class="monospaced">env</span>.  Like
 118 <span class="monospaced">Posix.Process.exece</span>.</p></div>
 119 </li>
 120 <li>
 121 <p>
 122 <span class="monospaced">spawnp {args, file}</span>
 123 </p>
 124 <div class="paragraph"><p>search the <span class="monospaced">PATH</span> environment variable for an executable named <span class="monospaced">file</span>,
 125 and start a new process running that executable with the arguments
 126 <span class="monospaced">args</span>.  Like <span class="monospaced">Posix.Process.execp</span>.</p></div>
 127 </li>
 128 </ul></div>
 129 </div>
 130 </div>
 131 <div class="sect1">
 132 <h2 id="_create">Create</h2>
 133 <div class="sectionbody">
 134 <div class="paragraph"><p><span class="monospaced">MLton.Process.create</span> provides functionality similar to
 135 <span class="monospaced">Unix.executeInEnv</span>, but provides more control control over the input,
 136 output, and error streams.  In addition, <span class="monospaced">create</span> works on all
 137 platforms, including Cygwin and MinGW (Windows) where <span class="monospaced">Posix.fork</span> is
 138 unavailable.  For greatest portability programs should still use the
 139 standard <span class="monospaced">Unix.execute</span>, <span class="monospaced">Unix.executeInEnv</span>, and <span class="monospaced">OS.Process.system</span>.</p></div>
 140 <div class="paragraph"><p>The following types and sub-structures are used by the <span class="monospaced">create</span>
 141 function.  They provide static type checking of correct stream usage.</p></div>
 142 <div class="sect2">
 143 <h3 id="_child">Child</h3>
 144 <div class="ulist"><ul>
 145 <li>
 146 <p>
 147 <span class="monospaced">('use, 'dir) Child.t</span>
 148 </p>
 149 <div class="paragraph"><p>This represents a handle to one of a child&#8217;s standard streams. The
 150 <span class="monospaced">'dir</span> is viewed with respect to the parent. Thus a <span class="monospaced">('a, input)
 151 Child.t</span> handle means that the parent may input the output from the
 152 child.</p></div>
 153 </li>
 154 <li>
 155 <p>
 156 <span class="monospaced">Child.{bin,text}{In,Out} h</span>
 157 </p>
 158 <div class="paragraph"><p>These functions take a handle and bind it to a stream of the named
 159 type.  The type system will detect attempts to reverse the direction
 160 of a stream or to use the same stream in multiple, incompatible ways.</p></div>
 161 </li>
 162 <li>
 163 <p>
 164 <span class="monospaced">Child.fd h</span>
 165 </p>
 166 <div class="paragraph"><p>This function behaves like the other <span class="monospaced">Child.*</span> functions; it opens a
 167 stream. However, it does not enforce that you read or write from the
 168 handle. If you use the descriptor in an inappropriate direction, the
 169 behavior is undefined. Furthermore, this function may potentially be
 170 unavailable on future MLton host platforms.</p></div>
 171 </li>
 172 <li>
 173 <p>
 174 <span class="monospaced">Child.remember h</span>
 175 </p>
 176 <div class="paragraph"><p>This function takes a stream of use <span class="monospaced">any</span> and resets the use of the
 177 stream so that the stream may be used by <span class="monospaced">Child.*</span>. An <span class="monospaced">any</span> stream
 178 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
 179 the stream was <span class="monospaced">none</span> and is used, <span class="monospaced">MisuseOfForget</span> is raised.</p></div>
 180 </li>
 181 </ul></div>
 182 </div>
 183 <div class="sect2">
 184 <h3 id="_param">Param</h3>
 185 <div class="ulist"><ul>
 186 <li>
 187 <p>
 188 <span class="monospaced">('use, 'dir) Param.t</span>
 189 </p>
 190 <div class="paragraph"><p>This is a handle to an input/output source and will be passed to the
 191 created child process. The <span class="monospaced">'dir</span> is relative to the child process.
 192 Input means that the child process will read from this stream.</p></div>
 193 </li>
 194 <li>
 195 <p>
 196 <span class="monospaced">Param.child h</span>
 197 </p>
 198 <div class="paragraph"><p>Connect the stream of the new child process to the stream of a
 199 previously created child process. A single child stream should be
 200 connected to only one child process or else <span class="monospaced">DoublyRedirected</span> will be
 201 raised.</p></div>
 202 </li>
 203 <li>
 204 <p>
 205 <span class="monospaced">Param.fd fd</span>
 206 </p>
 207 <div class="paragraph"><p>This creates a stream from the provided file descriptor which will be
 208 closed when <span class="monospaced">create</span> is called. This function may not be available on
 209 future MLton host platforms.</p></div>
 210 </li>
 211 <li>
 212 <p>
 213 <span class="monospaced">Param.forget h</span>
 214 </p>
 215 <div class="paragraph"><p>This hides the type of the actual parameter as <span class="monospaced">any</span>. This is useful
 216 if you are implementing an application which conditionally attaches
 217 the child process to files or pipes. However, you must ensure that
 218 your use after <span class="monospaced">Child.remember</span> matches the original type.</p></div>
 219 </li>
 220 <li>
 221 <p>
 222 <span class="monospaced">Param.file s</span>
 223 </p>
 224 <div class="paragraph"><p>Open the given file and connect it to the child process. Note that the
 225 file will be opened only when <span class="monospaced">create</span> is called. So any exceptions
 226 will be raised there and not by this function. If used for <span class="monospaced">input</span>,
 227 the file is opened read-only. If used for <span class="monospaced">output</span>, the file is opened
 228 read-write.</p></div>
 229 </li>
 230 <li>
 231 <p>
 232 <span class="monospaced">Param.null</span>
 233 </p>
 234 <div class="paragraph"><p>In some situations, the child process should have its output
 235 discarded.  The <span class="monospaced">null</span> param when passed as <span class="monospaced">stdout</span> or <span class="monospaced">stderr</span> does
 236 this.  When used for <span class="monospaced">stdin</span>, the child process will either receive
 237 <span class="monospaced">EOF</span> or a failure condition if it attempts to read from <span class="monospaced">stdin</span>.</p></div>
 238 </li>
 239 <li>
 240 <p>
 241 <span class="monospaced">Param.pipe</span>
 242 </p>
 243 <div class="paragraph"><p>This will connect the input/output of the child process to a pipe
 244 which the parent process holds. This may later form the input to one
 245 of the <span class="monospaced">Child.*</span> functions and/or the <span class="monospaced">Param.child</span> function.</p></div>
 246 </li>
 247 <li>
 248 <p>
 249 <span class="monospaced">Param.self</span>
 250 </p>
 251 <div class="paragraph"><p>This will connect the input/output of the child process to the
 252 corresponding stream of the parent process.</p></div>
 253 </li>
 254 </ul></div>
 255 </div>
 256 <div class="sect2">
 257 <h3 id="_process">Process</h3>
 258 <div class="ulist"><ul>
 259 <li>
 260 <p>
 261 <span class="monospaced">type ('stdin, 'stdout, 'stderr) t</span>
 262 </p>
 263 <div class="paragraph"><p>represents a handle to a child process.  The type arguments capture
 264 how the named stream of the child process may be used.</p></div>
 265 </li>
 266 <li>
 267 <p>
 268 <span class="monospaced">type any</span>
 269 </p>
 270 <div class="paragraph"><p>bypasses the type system in situations where an application does not
 271 want the it to enforce correct usage.  See <span class="monospaced">Child.remember</span> and
 272 <span class="monospaced">Param.forget</span>.</p></div>
 273 </li>
 274 <li>
 275 <p>
 276 <span class="monospaced">type chain</span>
 277 </p>
 278 <div class="paragraph"><p>means that the child process&#8217;s stream was connected via a pipe to the
 279 parent process. The parent process may pass this pipe in turn to
 280 another child, thus chaining them together.</p></div>
 281 </li>
 282 <li>
 283 <p>
 284 <span class="monospaced">type input, output</span>
 285 </p>
 286 <div class="paragraph"><p>record the direction that a stream flows.  They are used as a part of
 287 <span class="monospaced">Param.t</span> and <span class="monospaced">Child.t</span> and is detailed there.</p></div>
 288 </li>
 289 <li>
 290 <p>
 291 <span class="monospaced">type none</span>
 292 </p>
 293 <div class="paragraph"><p>means that the child process&#8217;s stream my not be used by the parent
 294 process.  This happens when the child process is connected directly to
 295 some source.</p></div>
 296 <div class="paragraph"><p>The types <span class="monospaced">BinIO.instream</span>, <span class="monospaced">BinIO.outstream</span>, <span class="monospaced">TextIO.instream</span>,
 297 <span class="monospaced">TextIO.outstream</span>, and <span class="monospaced">Posix.FileSys.file_desc</span> are also valid types
 298 with which to instantiate child streams.</p></div>
 299 </li>
 300 <li>
 301 <p>
 302 <span class="monospaced">exception MisuseOfForget</span>
 303 </p>
 304 <div class="paragraph"><p>may be raised if <span class="monospaced">Child.remember</span> and <span class="monospaced">Param.forget</span> are used to
 305 bypass the normal type checking.  This exception will only be raised
 306 in cases where the <span class="monospaced">forget</span> mechanism allows a misuse that would be
 307 impossible with the type-safe versions.</p></div>
 308 </li>
 309 <li>
 310 <p>
 311 <span class="monospaced">exception DoublyRedirected</span>
 312 </p>
 313 <div class="paragraph"><p>raised if a stream connected to a child process is redirected to two
 314 separate child processes.  It is safe, though bad style, to use the a
 315 <span class="monospaced">Child.t</span> with the same <span class="monospaced">Child.*</span> function repeatedly.</p></div>
 316 </li>
 317 <li>
 318 <p>
 319 <span class="monospaced">create {args, path, env, stderr, stdin, stdout}</span>
 320 </p>
 321 <div class="paragraph"><p>starts a child process with the given command-line <span class="monospaced">args</span> (excluding
 322 the program name). <span class="monospaced">path</span> should be an absolute path to the executable
 323 run in the new child process; relative paths work, but are less
 324 robust.  Optionally, the environment may be overridden with <span class="monospaced">env</span>
 325 where each string element has the form <span class="monospaced">"key=value"</span>. The <span class="monospaced">std*</span>
 326 options must be provided by the <span class="monospaced">Param.*</span> functions documented above.</p></div>
 327 <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>
 328 </li>
 329 <li>
 330 <p>
 331 <span class="monospaced">getStd{in,out,err} proc</span>
 332 </p>
 333 <div class="paragraph"><p>gets a handle to the specified stream. These should be used by the
 334 <span class="monospaced">Child.*</span> functions. Failure to use a stream connected via pipe to a
 335 child process may result in runtime dead-lock and elicits a compiler
 336 warning.</p></div>
 337 </li>
 338 <li>
 339 <p>
 340 <span class="monospaced">kill (proc, sig)</span>
 341 </p>
 342 <div class="paragraph"><p>terminates the child process immediately.  The signal may or may not
 343 mean anything depending on the host platform.  A good value is
 344 <span class="monospaced">Posix.Signal.term</span>.</p></div>
 345 </li>
 346 <li>
 347 <p>
 348 <span class="monospaced">reap proc</span>
 349 </p>
 350 <div class="paragraph"><p>waits for the child process to terminate and return its exit status.</p></div>
 351 </li>
 352 </ul></div>
 353 </div>
 354 </div>
 355 </div>
 356 <div class="sect1">
 357 <h2 id="_important_usage_notes">Important usage notes</h2>
 358 <div class="sectionbody">
 359 <div class="paragraph"><p>When building an application with many pipes between child processes,
 360 it is important to ensure that there are no cycles in the undirected
 361 pipe graph.  If this property is not maintained, deadlocks are a very
 362 serious potential bug which may only appear under difficult to
 363 reproduce conditions.</p></div>
 364 <div class="paragraph"><p>The danger lies in that most operating systems implement pipes with a
 365 fixed buffer size. If process A has two output pipes which process B
 366 reads, it can happen that process A blocks writing to pipe 2 because
 367 it is full while process B blocks reading from pipe 1 because it is
 368 empty. This same situation can happen with any undirected cycle formed
 369 between processes (vertexes) and pipes (undirected edges) in the
 370 graph.</p></div>
 371 <div class="paragraph"><p>It is possible to make this safe using low-level I/O primitives for
 372 polling.  However, these primitives are not very portable and
 373 difficult to use properly.  A far better approach is to make sure you
 374 never create a cycle in the first place.</p></div>
 375 <div class="paragraph"><p>For these reasons, the <span class="monospaced">Unix.executeInEnv</span> is a very dangerous
 376 function. Be careful when using it to ensure that the child process
 377 only operates on either <span class="monospaced">stdin</span> or <span class="monospaced">stdout</span>, but not both.</p></div>
 378 </div>
 379 </div>
 380 <div class="sect1">
 381 <h2 id="_example_use_of_mlton_process_create">Example use of MLton.Process.create</h2>
 382 <div class="sectionbody">
 383 <div class="paragraph"><p>The following example program launches the <span class="monospaced">ipconfig</span> utility, pipes
 384 its output through <span class="monospaced">grep</span>, and then reads the result back into the
 385 program.</p></div>
 386 <div class="listingblock">
 387 <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>
 388 <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>
 389 <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>
 390 <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>
 391 <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>
 392 <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>
 393 <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>
 394 <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>
 395 <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>
 396 <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>
 397 <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>
 398 <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>
 399 <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>
 400 <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>
 401 <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>
 402 <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>
 403 <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>
 404 <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>
 405 <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>
 406
 407 <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>
 408 </pre></div></div></div>
 409 </div>
 410 </div>
 411 </div>
 412 <div id="footnotes"><hr></div>
 413 <div id="footer">
 414 <div id="footer-text">
 415 </div>
 416 <div id="footer-badges">
 417 </div>
 418 </div>
 419 </body>
 420 </html>