/usr/share/doc/mlton/guide/MLtonProcess is in mlton-doc 20100608-5.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<meta name="robots" content="index,nofollow">
<title>MLtonProcess - MLton Standard ML Compiler (SML Compiler)</title>
<link rel="stylesheet" type="text/css" charset="iso-8859-1" media="all" href="common.css">
<link rel="stylesheet" type="text/css" charset="iso-8859-1" media="screen" href="screen.css">
<link rel="stylesheet" type="text/css" charset="iso-8859-1" media="print" href="print.css">
<link rel="Start" href="Home">
</head>
<body lang="en" dir="ltr">
<script src="http://www.google-analytics.com/urchin.js" type="text/javascript">
</script>
<script type="text/javascript">
_uacct = "UA-833377-1";
urchinTracker();
</script>
<table bgcolor = lightblue cellspacing = 0 style = "border: 0px;" width = 100%>
<tr>
<td style = "
border: 0px;
color: darkblue;
font-size: 150%;
text-align: left;">
<a class = mltona href="Home">MLton MLTONWIKIVERSION</a>
<td style = "
border: 0px;
font-size: 150%;
text-align: center;
width: 50%;">
MLtonProcess
<td style = "
border: 0px;
text-align: right;">
<table cellspacing = 0 style = "border: 0px">
<tr style = "vertical-align: middle;">
</table>
<tr style = "background-color: white;">
<td colspan = 3
style = "
border: 0px;
font-size:70%;
text-align: right;">
<a href = "Home">Home</a>
<a href = "TitleIndex">Index</a>
</table>
<div id="content" lang="en" dir="ltr">
<pre class=code>
<B><FONT COLOR="#0000FF">signature</FONT></B> MLTON_PROCESS =
<B><FONT COLOR="#0000FF">sig</FONT></B>
<B><FONT COLOR="#A020F0">type</FONT></B><B><FONT COLOR="#228B22"> pid
</FONT></B><B><FONT COLOR="#A020F0">val</FONT></B> spawn: {args: string list, path: string} -> pid
<B><FONT COLOR="#A020F0">val</FONT></B> spawne: {args: string list, env: string list, path: string} -> pid
<B><FONT COLOR="#A020F0">val</FONT></B> spawnp: {args: string list, file: string} -> pid
<B><FONT COLOR="#A020F0">type</FONT></B><B><FONT COLOR="#228B22"> ('stdin, 'stdout, 'stderr) t
</FONT></B><B><FONT COLOR="#A020F0">type</FONT></B><B><FONT COLOR="#228B22"> input
</FONT></B><B><FONT COLOR="#A020F0">type</FONT></B><B><FONT COLOR="#228B22"> output
</FONT></B><B><FONT COLOR="#A020F0">type</FONT></B><B><FONT COLOR="#228B22"> none
</FONT></B><B><FONT COLOR="#A020F0">type</FONT></B><B><FONT COLOR="#228B22"> chain
</FONT></B><B><FONT COLOR="#A020F0">type</FONT></B><B><FONT COLOR="#228B22"> any
</FONT></B><B><FONT COLOR="#A020F0">exception</FONT></B><B><FONT COLOR="#228B22"> <FONT COLOR="#B8860B">MisuseOfForget</FONT>
</FONT></B><B><FONT COLOR="#A020F0">exception</FONT></B><B><FONT COLOR="#228B22"> <FONT COLOR="#B8860B">DoublyRedirected</FONT>
</FONT></B><B><FONT COLOR="#0000FF">structure</FONT></B> Child:
<B><FONT COLOR="#0000FF">sig</FONT></B>
<B><FONT COLOR="#A020F0">type</FONT></B><B><FONT COLOR="#228B22"> ('use, 'dir) t
</FONT></B><B><FONT COLOR="#A020F0">val</FONT></B> binIn: (BinIO.instream, input) t -> BinIO.instream
<B><FONT COLOR="#A020F0">val</FONT></B> binOut: (BinIO.outstream, output) t -> BinIO.outstream
<B><FONT COLOR="#A020F0">val</FONT></B> fd: (Posix.FileSys.file_desc, 'dir) t -> Posix.FileSys.file_desc
<B><FONT COLOR="#A020F0">val</FONT></B> remember: (any, 'dir) t -> ('use, 'dir) t
<B><FONT COLOR="#A020F0">val</FONT></B> textIn: (TextIO.instream, input) t -> TextIO.instream
<B><FONT COLOR="#A020F0">val</FONT></B> textOut: (TextIO.outstream, output) t -> TextIO.outstream
<B><FONT COLOR="#0000FF">end</FONT></B>
<B><FONT COLOR="#0000FF">structure</FONT></B> Param:
<B><FONT COLOR="#0000FF">sig</FONT></B>
<B><FONT COLOR="#A020F0">type</FONT></B><B><FONT COLOR="#228B22"> ('use, 'dir) t
</FONT></B><B><FONT COLOR="#A020F0">val</FONT></B> child: (chain, 'dir) Child.t -> (none, 'dir) t
<B><FONT COLOR="#A020F0">val</FONT></B> fd: Posix.FileSys.file_desc -> (none, 'dir) t
<B><FONT COLOR="#A020F0">val</FONT></B> file: string -> (none, 'dir) t
<B><FONT COLOR="#A020F0">val</FONT></B> forget: ('use, 'dir) t -> (any, 'dir) t
<B><FONT COLOR="#A020F0">val</FONT></B> null: (none, 'dir) t
<B><FONT COLOR="#A020F0">val</FONT></B> pipe: ('use, 'dir) t
<B><FONT COLOR="#A020F0">val</FONT></B> self: (none, 'dir) t
<B><FONT COLOR="#0000FF">end</FONT></B>
<B><FONT COLOR="#A020F0">val</FONT></B> create:
{args: string list,
env: string list option,
path: string,
stderr: ('stderr, output) Param.t,
stdin: ('stdin, input) Param.t,
stdout: ('stdout, output) Param.t}
-> ('stdin, 'stdout, 'stderr) t
<B><FONT COLOR="#A020F0">val</FONT></B> getStderr: ('stdin, 'stdout, 'stderr) t -> ('stderr, input) Child.t
<B><FONT COLOR="#A020F0">val</FONT></B> getStdin: ('stdin, 'stdout, 'stderr) t -> ('stdin, output) Child.t
<B><FONT COLOR="#A020F0">val</FONT></B> getStdout: ('stdin, 'stdout, 'stderr) t -> ('stdout, input) Child.t
<B><FONT COLOR="#A020F0">val</FONT></B> kill: ('stdin, 'stdout, 'stderr) t * Posix.Signal.signal -> unit
<B><FONT COLOR="#A020F0">val</FONT></B> reap: ('stdin, 'stdout, 'stderr) t -> Posix.Process.exit_status
<B><FONT COLOR="#0000FF">end</FONT></B>
</PRE>
<p>
</p>
<h2 id="head-29de5042245abf38b78ad6189e060181d4ed060c">Spawn</h2>
<p>
The <tt>spawn</tt> functions provide an alternative to the <tt>fork</tt>/<tt>exec</tt> idiom that is typically used to create a new process. On most platforms, the <tt>spawn</tt> functions are simple wrappers around <tt>fork</tt>/<tt>exec</tt>. However, under Windows, the <tt>spawn</tt> functions are primitive. All <tt>spawn</tt> functions return the process id of the spawned process. They differ in how the executable is found and the environment that it uses.
</p>
<ul>
<li>
<p>
<tt>spawn {args, path} </tt> <br>
starts a new process running the executable specified by <tt>path</tt> with the arguments <tt>args</tt>. Like <tt>Posix.Process.exec</tt>.
</p>
</li>
<li class="gap">
<p>
<tt>spawne {args, env, path} </tt> <br>
starts a new process running the executable specified by <tt>path</tt> with the arguments <tt>args</tt> and environment <tt>env</tt>. Like <tt>Posix.Process.exece</tt>.
</p>
</li>
<li class="gap">
<p>
<tt>spawnp {args, file} </tt> <br>
search the <tt>PATH</tt> environment variable for an executable named <tt>file</tt>, and start a new process running that executable with the arguments <tt>args</tt>. Like <tt>Posix.Process.execp</tt>.
</p>
</li>
</ul>
<h2 id="head-6e157c5da4410b7e9de85f5c93026b9176e69064">Create</h2>
<p>
<tt>MLton.Process.create</tt> provides functionality similar to <tt>Unix.executeInEnv</tt>, but provides more control control over the input, output, and error streams. In addition, <tt>create</tt> works on all platforms, including Cygwin and MinGW (Windows) where <tt>Posix.fork</tt> is unavailable. For greatest portability programs should still use the standard <tt>Unix.execute</tt>, <tt>Unix.executeInEnv</tt>, and <tt>OS.Process.system</tt>.
</p>
<p>
The following types and sub-structures are used by the <tt>create</tt> function. They provide static type checking of correct stream usage.
</p>
<h3 id="head-6842c74c4d5122bd28c5c4fc9d30c451e8a95d41">Child</h3>
<ul>
<li>
<p>
<tt>('use, 'dir) Child.t</tt> <br>
This represents a handle to one of a child's standard streams. The <tt>'dir</tt> is viewed with respect to the parent. Thus a <tt>('a, input) Child.t</tt> handle means that the parent may input the output from the child.
</p>
</li>
<li class="gap">
<p>
<tt>Child.{bin,text}{In,Out} h</tt> <br>
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>
</li>
<li class="gap">
<p>
<tt>Child.fd h</tt> <br>
This function behaves like the other <tt>Child.*</tt> 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>
</li>
<li class="gap">
<p>
<tt>Child.remember h</tt> <br>
This function takes a stream of use <tt>any</tt> and resets the use of the stream so that the stream may be used by <tt>Child.*</tt>. An <tt>any</tt> stream may have had use <tt>none</tt> or <tt>'use</tt> prior to calling <tt>Param.forget</tt>. If the stream was <tt>none</tt> and is used, <tt>MisuseOfForget</tt> is raised.
</p>
</li>
</ul>
<h3 id="head-0f332eeefd007bb0043ccb46738196508c6a602b">Param</h3>
<ul>
<li>
<p>
<tt>('use, 'dir) Param.t</tt> <br>
This is a handle to an input/output source and will be passed to the created child process. The <tt>'dir</tt> is relative to the child process. Input means that the child process will read from this stream.
</p>
</li>
<li class="gap">
<p>
<tt>Param.child h</tt> <br>
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 <tt>DoublyRedirected</tt> will be raised.
</p>
</li>
<li class="gap">
<p>
<tt>Param.fd fd</tt> <br>
This creates a stream from the provided file descriptor which will be closed when <tt>create</tt> is called. This function may not be available on future MLton host platforms.
</p>
</li>
<li class="gap">
<p>
<tt>Param.forget h</tt> <br>
This hides the type of the actual parameter as <tt>any</tt>. 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 <tt>Child.remember</tt> matches the original type.
</p>
</li>
<li class="gap">
<p>
<tt>Param.file s</tt> <br>
Open the given file and connect it to the child process. Note that the file will be opened only when <tt>create</tt> is called. So any exceptions will be raised there and not by this function. If used for <tt>input</tt>, the file is opened read-only. If used for <tt>output</tt>, the file is opened read-write.
</p>
</li>
<li class="gap">
<p>
<tt>Param.null</tt> <br>
In some situations, the child process should have its output discarded. The <tt>null</tt> param when passed as <tt>stdout</tt> or <tt>stderr</tt> does this. When used for <tt>stdin</tt>, the child process will either receive <tt>EOF</tt> or a failure condition if it attempts to read from <tt>stdin</tt>.
</p>
</li>
<li class="gap">
<p>
<tt>Param.pipe</tt> <br>
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 <tt>Child.*</tt> functions and/or the <tt>Param.child</tt> function.
</p>
</li>
<li class="gap">
<p>
<tt>Param.self</tt> <br>
This will connect the input/output of the child process to the corresponding stream of the parent process.
</p>
</li>
</ul>
<h3 id="head-12f4c13a6a06f999cc56eb966c94f71ef2658a3f">Process</h3>
<ul>
<li>
<p>
<tt>type ('stdin, 'stdout, 'stderr) t</tt> <br>
represents a handle to a child process. The type arguments capture how the named stream of the child process may be used.
</p>
</li>
<li class="gap">
<p>
<tt>type any</tt> <br>
bypasses the type system in situations where an application does not want the it to enforce correct usage. See <tt>Child.remember</tt> and <tt>Param.forget</tt>.
</p>
</li>
<li class="gap">
<p>
<tt>type chain</tt> <br>
means that the child process'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>
</li>
<li class="gap">
<p>
<tt>type input, output</tt> <br>
record the direction that a stream flows. They are used as a part of <tt>Param.t</tt> and <tt>Child.t</tt> and is detailed there.
</p>
</li>
<li class="gap">
<p>
<tt>type none</tt> <br>
means that the child process's stream my not be used by the parent process. This happens when the child process is connected directly to some source.
</p>
</li>
</ul>
<p>
The types <tt>BinIO.instream</tt>, <tt>BinIO.outstream</tt>, <tt>TextIO.instream</tt>, <tt>TextIO.outstream</tt>, and <tt>Posix.FileSys.file_desc</tt> are also valid types with which to instantiate child streams.
</p>
<ul>
<li>
<p>
<tt>exception MisuseOfForget</tt> <br>
may be raised if <tt>Child.remember</tt> and <tt>Param.forget</tt> are used to bypass the normal type checking. This exception will only be raised in cases where the <tt>forget</tt> mechanism allows a misuse that would be impossible with the type-safe versions.
</p>
</li>
<li class="gap">
<p>
<tt>exception DoublyRedirected</tt> <br>
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 <tt>Child.t</tt> with the same <tt>Child.*</tt> function repeatedly.
</p>
</li>
<li class="gap">
<p>
<tt>create {args, path, env, stderr, stdin, stdout} </tt> <br>
starts a child process with the given command-line <tt>args</tt> (excluding the program name). <tt>path</tt> 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 <tt>env</tt> where each string element has the form <tt>"key=value"</tt>. The <tt>std*</tt> options must be provided by the <tt>Param.*</tt> functions documented above.
</p>
<p>
Processes which are <tt>create</tt>d must be either <tt>reap</tt>ed or <tt>kill</tt>ed.
</p>
</li>
<li class="gap">
<p>
<tt>getStd{in,out,err} proc</tt> <br>
gets a handle to the specified stream. These should be used by the <tt>Child.*</tt> 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>
</li>
<li class="gap">
<p>
<tt>kill (proc, sig)</tt> <br>
terminates the child process immediately. The signal may or may not mean anything depending on the host platform. A good value is <tt>Posix.Signal.term</tt>.
</p>
</li>
<li class="gap">
<p>
<tt>reap proc</tt> <br>
waits for the child process to terminate and return its exit status.
</p>
</li>
</ul>
<h2 id="head-1bd1007a907ddfb4201460172ceb074df91cb3a0">Important usage notes</h2>
<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>
<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>
<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>
<p>
For these reasons, the <tt>Unix.executeInEnv</tt> is a very dangerous function. Be careful when using it to ensure that the child process only operates on either <tt>stdin</tt> or <tt>stdout</tt>, but not both.
</p>
<h2 id="head-b1a8792f7ebf2c8e409e3a2a6fb1080258106995">Example use of MLton.Process.create</h2>
<p>
The following example program launches the <tt>ipconfig</tt> utility, pipes its output through <tt>grep</tt>, and then reads the result back into the program.
</p>
<pre class=code>
<B><FONT COLOR="#0000FF">open</FONT></B> MLton.Process
<B><FONT COLOR="#A020F0">val</FONT></B> p =
create {args = [ <B><FONT COLOR="#BC8F8F">"/all"</FONT></B> ],
env = NONE,
path = <B><FONT COLOR="#BC8F8F">"C:\\WINDOWS\\system32\\ipconfig.exe"</FONT></B>,
stderr = Param.self,
stdin = Param.null,
stdout = Param.pipe}
<B><FONT COLOR="#A020F0">val</FONT></B> q =
create {args = [ <B><FONT COLOR="#BC8F8F">"IP-Ad"</FONT></B> ],
env = NONE,
path = <B><FONT COLOR="#BC8F8F">"C:\\msys\\bin\\grep.exe"</FONT></B>,
stderr = Param.self,
stdin = Param.child (getStdout p),
stdout = Param.pipe}
<B><FONT COLOR="#A020F0">fun</FONT></B> suck h =
<B><FONT COLOR="#A020F0">case</FONT></B> TextIO.inputLine h <B><FONT COLOR="#A020F0">of</FONT></B>
NONE => ()
| SOME s => (print (<B><FONT COLOR="#BC8F8F">"'"</FONT></B> ^ s ^ <B><FONT COLOR="#BC8F8F">"'\n"</FONT></B>); suck h)
<B><FONT COLOR="#A020F0">val</FONT></B> () = suck (Child.textIn (getStdout q))
</PRE>
<p>
</p>
</div>
<p>
<hr>
Last edited on 2009-06-15 22:22:05 by <span title="fenrir.uchicago.edu"><a href="MatthewFluet">MatthewFluet</a></span>.
</body></html>
|