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