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
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<link rel="stylesheet" href="style.css" type="text/css">
<meta content="text/html; charset=iso-8859-1" http-equiv="Content-Type">
<link rel="Start" href="index.html">
<link rel="previous" href="Equeue.html">
<link rel="next" href="Uq_engines.html">
<link rel="Up" href="index.html">
<link title="Index of types" rel=Appendix href="index_types.html">
<link title="Index of exceptions" rel=Appendix href="index_exceptions.html">
<link title="Index of values" rel=Appendix href="index_values.html">
<link title="Index of class attributes" rel=Appendix href="index_attributes.html">
<link title="Index of class methods" rel=Appendix href="index_methods.html">
<link title="Index of classes" rel=Appendix href="index_classes.html">
<link title="Index of class types" rel=Appendix href="index_class_types.html">
<link title="Index of modules" rel=Appendix href="index_modules.html">
<link title="Index of module types" rel=Appendix href="index_module_types.html">
<link title="Uq_gtk" rel="Chapter" href="Uq_gtk.html">
<link title="Equeue" rel="Chapter" href="Equeue.html">
<link title="Unixqueue" rel="Chapter" href="Unixqueue.html">
<link title="Uq_engines" rel="Chapter" href="Uq_engines.html">
<link title="Uq_socks5" rel="Chapter" href="Uq_socks5.html">
<link title="Unixqueue_mt" rel="Chapter" href="Unixqueue_mt.html">
<link title="Equeue_intro" rel="Chapter" href="Equeue_intro.html">
<link title="Uq_ssl" rel="Chapter" href="Uq_ssl.html">
<link title="Uq_tcl" rel="Chapter" href="Uq_tcl.html">
<link title="Netcgi_common" rel="Chapter" href="Netcgi_common.html">
<link title="Netcgi" rel="Chapter" href="Netcgi.html">
<link title="Netcgi_ajp" rel="Chapter" href="Netcgi_ajp.html">
<link title="Netcgi_scgi" rel="Chapter" href="Netcgi_scgi.html">
<link title="Netcgi_cgi" rel="Chapter" href="Netcgi_cgi.html">
<link title="Netcgi_fcgi" rel="Chapter" href="Netcgi_fcgi.html">
<link title="Netcgi_dbi" rel="Chapter" href="Netcgi_dbi.html">
<link title="Netcgi1_compat" rel="Chapter" href="Netcgi1_compat.html">
<link title="Netcgi_test" rel="Chapter" href="Netcgi_test.html">
<link title="Netcgi_porting" rel="Chapter" href="Netcgi_porting.html">
<link title="Netcgi_plex" rel="Chapter" href="Netcgi_plex.html">
<link title="Http_client" rel="Chapter" href="Http_client.html">
<link title="Telnet_client" rel="Chapter" href="Telnet_client.html">
<link title="Ftp_data_endpoint" rel="Chapter" href="Ftp_data_endpoint.html">
<link title="Ftp_client" rel="Chapter" href="Ftp_client.html">
<link title="Nethttpd_types" rel="Chapter" href="Nethttpd_types.html">
<link title="Nethttpd_kernel" rel="Chapter" href="Nethttpd_kernel.html">
<link title="Nethttpd_reactor" rel="Chapter" href="Nethttpd_reactor.html">
<link title="Nethttpd_engine" rel="Chapter" href="Nethttpd_engine.html">
<link title="Nethttpd_services" rel="Chapter" href="Nethttpd_services.html">
<link title="Nethttpd_plex" rel="Chapter" href="Nethttpd_plex.html">
<link title="Nethttpd_intro" rel="Chapter" href="Nethttpd_intro.html">
<link title="Netplex_types" rel="Chapter" href="Netplex_types.html">
<link title="Netplex_mp" rel="Chapter" href="Netplex_mp.html">
<link title="Netplex_mt" rel="Chapter" href="Netplex_mt.html">
<link title="Netplex_log" rel="Chapter" href="Netplex_log.html">
<link title="Netplex_controller" rel="Chapter" href="Netplex_controller.html">
<link title="Netplex_container" rel="Chapter" href="Netplex_container.html">
<link title="Netplex_sockserv" rel="Chapter" href="Netplex_sockserv.html">
<link title="Netplex_workload" rel="Chapter" href="Netplex_workload.html">
<link title="Netplex_main" rel="Chapter" href="Netplex_main.html">
<link title="Netplex_config" rel="Chapter" href="Netplex_config.html">
<link title="Netplex_kit" rel="Chapter" href="Netplex_kit.html">
<link title="Rpc_netplex" rel="Chapter" href="Rpc_netplex.html">
<link title="Netplex_cenv" rel="Chapter" href="Netplex_cenv.html">
<link title="Netplex_intro" rel="Chapter" href="Netplex_intro.html">
<link title="Netshm" rel="Chapter" href="Netshm.html">
<link title="Netshm_data" rel="Chapter" href="Netshm_data.html">
<link title="Netshm_hashtbl" rel="Chapter" href="Netshm_hashtbl.html">
<link title="Netshm_array" rel="Chapter" href="Netshm_array.html">
<link title="Netshm_intro" rel="Chapter" href="Netshm_intro.html">
<link title="Netconversion" rel="Chapter" href="Netconversion.html">
<link title="Netchannels" rel="Chapter" href="Netchannels.html">
<link title="Netstream" rel="Chapter" href="Netstream.html">
<link title="Mimestring" rel="Chapter" href="Mimestring.html">
<link title="Netmime" rel="Chapter" href="Netmime.html">
<link title="Netsendmail" rel="Chapter" href="Netsendmail.html">
<link title="Neturl" rel="Chapter" href="Neturl.html">
<link title="Netaddress" rel="Chapter" href="Netaddress.html">
<link title="Netbuffer" rel="Chapter" href="Netbuffer.html">
<link title="Netdate" rel="Chapter" href="Netdate.html">
<link title="Netencoding" rel="Chapter" href="Netencoding.html">
<link title="Netulex" rel="Chapter" href="Netulex.html">
<link title="Netaccel" rel="Chapter" href="Netaccel.html">
<link title="Netaccel_link" rel="Chapter" href="Netaccel_link.html">
<link title="Nethtml" rel="Chapter" href="Nethtml.html">
<link title="Netstring_str" rel="Chapter" href="Netstring_str.html">
<link title="Netstring_pcre" rel="Chapter" href="Netstring_pcre.html">
<link title="Netstring_mt" rel="Chapter" href="Netstring_mt.html">
<link title="Netmappings" rel="Chapter" href="Netmappings.html">
<link title="Netaux" rel="Chapter" href="Netaux.html">
<link title="Nethttp" rel="Chapter" href="Nethttp.html">
<link title="Netchannels_tut" rel="Chapter" href="Netchannels_tut.html">
<link title="Netmime_tut" rel="Chapter" href="Netmime_tut.html">
<link title="Netsendmail_tut" rel="Chapter" href="Netsendmail_tut.html">
<link title="Netulex_tut" rel="Chapter" href="Netulex_tut.html">
<link title="Neturl_tut" rel="Chapter" href="Neturl_tut.html">
<link title="Netsys" rel="Chapter" href="Netsys.html">
<link title="Netpop" rel="Chapter" href="Netpop.html">
<link title="Rpc_auth_dh" rel="Chapter" href="Rpc_auth_dh.html">
<link title="Rpc_key_service" rel="Chapter" href="Rpc_key_service.html">
<link title="Rpc_time" rel="Chapter" href="Rpc_time.html">
<link title="Rpc_auth_local" rel="Chapter" href="Rpc_auth_local.html">
<link title="Rtypes" rel="Chapter" href="Rtypes.html">
<link title="Xdr" rel="Chapter" href="Xdr.html">
<link title="Rpc" rel="Chapter" href="Rpc.html">
<link title="Rpc_program" rel="Chapter" href="Rpc_program.html">
<link title="Rpc_portmapper_aux" rel="Chapter" href="Rpc_portmapper_aux.html">
<link title="Rpc_packer" rel="Chapter" href="Rpc_packer.html">
<link title="Rpc_transport" rel="Chapter" href="Rpc_transport.html">
<link title="Rpc_client" rel="Chapter" href="Rpc_client.html">
<link title="Rpc_simple_client" rel="Chapter" href="Rpc_simple_client.html">
<link title="Rpc_portmapper_clnt" rel="Chapter" href="Rpc_portmapper_clnt.html">
<link title="Rpc_portmapper" rel="Chapter" href="Rpc_portmapper.html">
<link title="Rpc_server" rel="Chapter" href="Rpc_server.html">
<link title="Rpc_auth_sys" rel="Chapter" href="Rpc_auth_sys.html">
<link title="Rpc_intro" rel="Chapter" href="Rpc_intro.html">
<link title="Rpc_mapping_ref" rel="Chapter" href="Rpc_mapping_ref.html">
<link title="Rpc_ssl" rel="Chapter" href="Rpc_ssl.html">
<link title="Rpc_xti_client" rel="Chapter" href="Rpc_xti_client.html">
<link title="Shell_sys" rel="Chapter" href="Shell_sys.html">
<link title="Shell" rel="Chapter" href="Shell.html">
<link title="Shell_uq" rel="Chapter" href="Shell_uq.html">
<link title="Shell_mt" rel="Chapter" href="Shell_mt.html">
<link title="Shell_intro" rel="Chapter" href="Shell_intro.html">
<link title="Netsmtp" rel="Chapter" href="Netsmtp.html"><title>Ocamlnet 2 Reference Manual : Unixqueue</title>
</head>
<body>
<div class="navbar"><a href="Equeue.html">Previous</a>
<a href="index.html">Up</a>
<a href="Uq_engines.html">Next</a>
</div>
<center><h1>Module <a href="type_Unixqueue.html">Unixqueue</a></h1></center>
<br>
<pre><span class="keyword">module</span> Unixqueue: <code class="code">sig</code> <a href="Unixqueue.html">..</a> <code class="code">end</code></pre>This module generalizes the <code class="code">Unix.select</code> function. The idea is to have
an event queue (implemented by <a href="Equeue.html"><code class="code">Equeue</code></a>) that manages all file events that
can be watched by a <code class="code">Unix.select</code> call. As <b>event</b> is considered when there
is something to do for a file descriptor (reading, writing, accepting
out-of-band data), but also the condition that for a certain period
of time ("timeout") nothing
has happened. Furthermore, a signal is also considered as an event,
and it is also possible to have user-generated extra events.
<p>
These events are queued up, and they are presented to event handlers
that may process them.
<p>
You can describe what types of event conditions are watched by adding
"resources". You can think a resource being a condition (bound to
a real resource of the operating system) for which
events are generated if the condition becomes true.<br>
<hr width="100%">
<br>
This module generalizes the <code class="code">Unix.select</code> function. The idea is to have
an event queue (implemented by <a href="Equeue.html"><code class="code">Equeue</code></a>) that manages all file events that
can be watched by a <code class="code">Unix.select</code> call. As <b>event</b> is considered when there
is something to do for a file descriptor (reading, writing, accepting
out-of-band data), but also the condition that for a certain period
of time ("timeout") nothing
has happened. Furthermore, a signal is also considered as an event,
and it is also possible to have user-generated extra events.
<p>
These events are queued up, and they are presented to event handlers
that may process them.
<p>
You can describe what types of event conditions are watched by adding
"resources". You can think a resource being a condition (bound to
a real resource of the operating system) for which
events are generated if the condition becomes true.<br>
<br>
<b>THREAD-SAFETY</b>
<p>
Since release 1.2 of Equeue, this module serializes automatically.
You can call functions for the same event system from different
threads. This requires some special initialization, see <a href="Unixqueue_mt.html"><code class="code">Unixqueue_mt</code></a>.
<p>
Note that the underlying <a href="Equeue.html"><code class="code">Equeue</code></a> module is reentrant, but not
serializing. (It is not recommended (and not necessary) to call
functions of the Equeue module directly in multi-threaded programs.)
<p>
The TCL extension is not thread-safe.<br>
<pre><span class="keyword">type</span> <a name="TYPEgroup"></a><code class="type"></code>group </pre>
<div class="info">
A group is an abstract tag for a set of events, resources, and
event handlers. Usually every event handler creates a new group,
and all events and resources processed by the handler are
members of this group.<br>
</div>
<pre><span class="keyword">exception</span> <a name="EXCEPTIONAbort"></a>Abort <span class="keyword">of</span> <code class="type">(<a href="Unixqueue.html#TYPEgroup">group</a> * exn)</code></pre>
<div class="info">
Event handlers can raise this exception to cancel a group
of handlers, events, and resources. If an abort action
is defined for the group, it will be executed. Next, all members
of the group are removed from the event system.
<p>
First argument is the group. The second argument
is an arbitrary exception (must not be <code class="code">Abort</code> again) which is
passed to the abort action.<br>
</div>
<pre><span class="keyword">type</span> <a name="TYPEwait_id"></a><code class="type"></code>wait_id </pre>
<div class="info">
A wait identifier is used to distinguish between several
timers, see type <code class="code">operation</code>.<br>
</div>
<br><code><span class="keyword">type</span> <a name="TYPEoperation"></a><code class="type"></code>operation = </code><table class="typetable">
<tr>
<td align="left" valign="top" >
<code><span class="keyword">|</span></code></td>
<td align="left" valign="top" >
<code><span class="constructor">Wait_in</span> <span class="keyword">of</span> <code class="type">Unix.file_descr</code></code></td>
<td class="typefieldcomment" align="left" valign="top" ><code>(*</code></td><td class="typefieldcomment" align="left" valign="top" >wait for input data</td><td class="typefieldcomment" align="left" valign="bottom" ><code>*)</code></td>
</tr>
<tr>
<td align="left" valign="top" >
<code><span class="keyword">|</span></code></td>
<td align="left" valign="top" >
<code><span class="constructor">Wait_out</span> <span class="keyword">of</span> <code class="type">Unix.file_descr</code></code></td>
<td class="typefieldcomment" align="left" valign="top" ><code>(*</code></td><td class="typefieldcomment" align="left" valign="top" >wait until output can be written</td><td class="typefieldcomment" align="left" valign="bottom" ><code>*)</code></td>
</tr>
<tr>
<td align="left" valign="top" >
<code><span class="keyword">|</span></code></td>
<td align="left" valign="top" >
<code><span class="constructor">Wait_oob</span> <span class="keyword">of</span> <code class="type">Unix.file_descr</code></code></td>
<td class="typefieldcomment" align="left" valign="top" ><code>(*</code></td><td class="typefieldcomment" align="left" valign="top" >wait for out-of-band data</td><td class="typefieldcomment" align="left" valign="bottom" ><code>*)</code></td>
</tr>
<tr>
<td align="left" valign="top" >
<code><span class="keyword">|</span></code></td>
<td align="left" valign="top" >
<code><span class="constructor">Wait</span> <span class="keyword">of</span> <code class="type"><a href="Unixqueue.html#TYPEwait_id">wait_id</a></code></code></td>
<td class="typefieldcomment" align="left" valign="top" ><code>(*</code></td><td class="typefieldcomment" align="left" valign="top" >wait only for timeout</td><td class="typefieldcomment" align="left" valign="bottom" ><code>*)</code></td>
</tr></table>
<div class="info">
An <code class="code">operation</code> specifies the condition to wait for. Every kind
of operation may have an associated timer (not only <code class="code">Wait</code>).<br>
</div>
<br><code><span class="keyword">type</span> <a name="TYPEevent"></a><code class="type"></code>event = </code><table class="typetable">
<tr>
<td align="left" valign="top" >
<code><span class="keyword">|</span></code></td>
<td align="left" valign="top" >
<code><span class="constructor">Input_arrived</span> <span class="keyword">of</span> <code class="type">(<a href="Unixqueue.html#TYPEgroup">group</a> * Unix.file_descr)</code></code></td>
<td class="typefieldcomment" align="left" valign="top" ><code>(*</code></td><td class="typefieldcomment" align="left" valign="top" >Input data has arrived</td><td class="typefieldcomment" align="left" valign="bottom" ><code>*)</code></td>
</tr>
<tr>
<td align="left" valign="top" >
<code><span class="keyword">|</span></code></td>
<td align="left" valign="top" >
<code><span class="constructor">Output_readiness</span> <span class="keyword">of</span> <code class="type">(<a href="Unixqueue.html#TYPEgroup">group</a> * Unix.file_descr)</code></code></td>
<td class="typefieldcomment" align="left" valign="top" ><code>(*</code></td><td class="typefieldcomment" align="left" valign="top" >Output is possible now</td><td class="typefieldcomment" align="left" valign="bottom" ><code>*)</code></td>
</tr>
<tr>
<td align="left" valign="top" >
<code><span class="keyword">|</span></code></td>
<td align="left" valign="top" >
<code><span class="constructor">Out_of_band</span> <span class="keyword">of</span> <code class="type">(<a href="Unixqueue.html#TYPEgroup">group</a> * Unix.file_descr)</code></code></td>
<td class="typefieldcomment" align="left" valign="top" ><code>(*</code></td><td class="typefieldcomment" align="left" valign="top" >OOB data has arrived</td><td class="typefieldcomment" align="left" valign="bottom" ><code>*)</code></td>
</tr>
<tr>
<td align="left" valign="top" >
<code><span class="keyword">|</span></code></td>
<td align="left" valign="top" >
<code><span class="constructor">Timeout</span> <span class="keyword">of</span> <code class="type">(<a href="Unixqueue.html#TYPEgroup">group</a> * <a href="Unixqueue.html#TYPEoperation">operation</a>)</code></code></td>
<td class="typefieldcomment" align="left" valign="top" ><code>(*</code></td><td class="typefieldcomment" align="left" valign="top" >A timer has expired</td><td class="typefieldcomment" align="left" valign="bottom" ><code>*)</code></td>
</tr>
<tr>
<td align="left" valign="top" >
<code><span class="keyword">|</span></code></td>
<td align="left" valign="top" >
<code><span class="constructor">Signal</span></code></td>
<td class="typefieldcomment" align="left" valign="top" ><code>(*</code></td><td class="typefieldcomment" align="left" valign="top" >A signal has happened</td><td class="typefieldcomment" align="left" valign="bottom" ><code>*)</code></td>
</tr>
<tr>
<td align="left" valign="top" >
<code><span class="keyword">|</span></code></td>
<td align="left" valign="top" >
<code><span class="constructor">Extra</span> <span class="keyword">of</span> <code class="type">exn</code></code></td>
<td class="typefieldcomment" align="left" valign="top" ><code>(*</code></td><td class="typefieldcomment" align="left" valign="top" >User-generated event</td><td class="typefieldcomment" align="left" valign="bottom" ><code>*)</code></td>
</tr></table>
<div class="info">
An <code class="code">event</code> is triggered when the condition of an <code class="code">operation</code>
becomes true, when a signal happens, or when the event is
(artificially) added to the event queue (<code class="code">add_event</code>, below).
The events resulting from an <code class="code">operation</code> carry the group of
the resource with them.
<p>
The event <code class="code">Signal</code> is triggered when the <code class="code">EINTR</code> condition is
caught; this normally means that a signal has just been delivered.
The generation of <code class="code">Signal</code> events should be considered as
unreliable, not every signal delivery can be detected. Reasons for
the unrealiability are that user-supplied code happens to
get the <code class="code">EINTR</code> condition and not the <code class="code">Unixqueue</code> event loop,
and that there are known race conditions in the O'Caml signal
handling routines that may cause signals to be lost. However,
it can be expected that almost all signals will trigger <code class="code">Signal</code>.
<p>
The event <code class="code">Extra</code> can only be artificially added to the queue,
and the argument of <code class="code">Extra</code> is an exception value that distinguishes
between several kinds of user-generated events.<br>
</div>
<pre><span class="keyword">class type</span> <a name="TYPEevent_system"></a><a href="Unixqueue.event_system.html">event_system</a> = <code class="code">object</code> <a href="Unixqueue.event_system.html">..</a> <code class="code">end</code></pre><div class="info">
The <code class="code">event_system</code> manages events, handlers, resources, groups,
etc.
</div>
<pre><span class="keyword">class</span> <a name="TYPEunix_event_system"></a><a href="Unixqueue.unix_event_system.html">unix_event_system</a> : <code class="type">unit -> </code><code class="type"><a href="Unixqueue.event_system.html">event_system</a></code></pre><div class="info">
The standalone implementation of an event system
</div>
<pre><span class="keyword">val</span> <a name="VALcreate_unix_event_system"></a>create_unix_event_system : <code class="type">unit -> <a href="Unixqueue.event_system.html">event_system</a></code></pre><div class="info">
Create a new, empty event system<br>
</div>
<pre><span class="keyword">val</span> <a name="VALnew_group"></a>new_group : <code class="type"><a href="Unixqueue.event_system.html">event_system</a> -> <a href="Unixqueue.html#TYPEgroup">group</a></code></pre><div class="info">
Create a new, empty group for the event system<br>
</div>
<pre><span class="keyword">val</span> <a name="VALnew_wait_id"></a>new_wait_id : <code class="type"><a href="Unixqueue.event_system.html">event_system</a> -> <a href="Unixqueue.html#TYPEwait_id">wait_id</a></code></pre><div class="info">
Create a new unique wait identifier<br>
</div>
<pre><span class="keyword">val</span> <a name="VALexists_resource"></a>exists_resource : <code class="type"><a href="Unixqueue.event_system.html">event_system</a> -> <a href="Unixqueue.html#TYPEoperation">operation</a> -> bool</code></pre><div class="info">
Find out if a specific resource already exists (or better: is
already watched by an operation).<br>
</div>
<pre><span class="keyword">val</span> <a name="VALadd_resource"></a>add_resource : <code class="type"><a href="Unixqueue.event_system.html">event_system</a> -><br> <a href="Unixqueue.html#TYPEgroup">group</a> -> <a href="Unixqueue.html#TYPEoperation">operation</a> * float -> unit</code></pre><div class="info">
Add a resource such that it is watched for conditions described
by the <code class="code">operation</code> for the period given by the <code class="code">float</code> number.
A negative number means that the resource is watched for an infinite
period. The resource becomes a member of the <code class="code">group</code>.
<p>
You cannot add the same operation several times;
if you try it the second operation is silently dropped.
<p>
The resource remains even if it has generated an event. The timeout
period starts again in this case.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALadd_close_action"></a>add_close_action : <code class="type"><a href="Unixqueue.event_system.html">event_system</a> -><br> <a href="Unixqueue.html#TYPEgroup">group</a> -> Unix.file_descr * (Unix.file_descr -> unit) -> unit</code></pre><div class="info">
A close action is added for the file descriptor. The action callback
(which gets the descriptor as argument) is called when there is not
any watched resource remaining for this descriptor.
<p>
This may be useful if the descriptor can be closed in this case.
<p>
The close action becomes member of the passed <code class="code">group</code>. The only
effect of this is that the action is removed when the <code class="code">clear</code> function
is called.
<p>
You can only add (set) one close action for every descriptor.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALadd_abort_action"></a>add_abort_action : <code class="type"><a href="Unixqueue.event_system.html">event_system</a> -><br> <a href="Unixqueue.html#TYPEgroup">group</a> -> (<a href="Unixqueue.html#TYPEgroup">group</a> -> exn -> unit) -> unit</code></pre><div class="info">
An abort action is added to the group. The action callback is
called when an arbitrary handler raises <code class="code">Abort(g,exn)</code> where
<code class="code">g</code> is the group the abort action is member of. In this case,
the callback function is invoked with the group and <code class="code">exn</code> as
arguments. After that, the group is cleared.
<p>
You can only add (set) one abort action for every group.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALremove_resource"></a>remove_resource : <code class="type"><a href="Unixqueue.event_system.html">event_system</a> -> <a href="Unixqueue.html#TYPEgroup">group</a> -> <a href="Unixqueue.html#TYPEoperation">operation</a> -> unit</code></pre><div class="info">
Removes the operation from the watch list of the group.
It is an error if the operation is member of another group.
If the operation cannot be found at all, the exception <code class="code">Not_found</code>
will be raised.
<p>
The removal of resources may trigger close actions.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALadd_handler"></a>add_handler : <code class="type"><a href="Unixqueue.event_system.html">event_system</a> -><br> <a href="Unixqueue.html#TYPEgroup">group</a> -><br> (<a href="Unixqueue.event_system.html">event_system</a> -><br> <a href="Unixqueue.html#TYPEevent">event</a> <a href="Equeue.html#TYPEt">Equeue.t</a> -> <a href="Unixqueue.html#TYPEevent">event</a> -> unit) -><br> unit</code></pre><div class="info">
Add an event handler that is associated to the given group. There
may be several handlers for a group.
<p>
The handler callback function is invoked when there is an event
that could be processeable by the handler. As outlined above, the
callback function can accept or reject the event, it can terminate
itself, and it can abort the whole group.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALadd_event"></a>add_event : <code class="type"><a href="Unixqueue.event_system.html">event_system</a> -> <a href="Unixqueue.html#TYPEevent">event</a> -> unit</code></pre><div class="info">
Add an additional event. The event will be processed after the
current list of events is done.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALclear"></a>clear : <code class="type"><a href="Unixqueue.event_system.html">event_system</a> -> <a href="Unixqueue.html#TYPEgroup">group</a> -> unit</code></pre><div class="info">
Terminate the whole group. This means that the handlers of the
group are not called any longer, and that all resources and actions
are removed. It is possible that there are pending events after
termination, but these will be usually be dropped because there is
no handler for them.
<p>
When a group is terminated, it is not allowed to refer to the
group any longer. Functions will raise <code class="code">Invalid_argument</code> if this
is tried nevertheless.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALrun"></a>run : <code class="type"><a href="Unixqueue.event_system.html">event_system</a> -> unit</code></pre><div class="info">
Starts the event loop. This means that the resources are watched,
and that events are generated, and that handlers are called.
<p>
The event loop returns normally when there are not any resources
and not any events in the queue. The loop raises
<a href="Equeue.html#EXCEPTIONOut_of_handlers"><code class="code">Equeue.Out_of_handlers</code></a> if there are resources but no handlers
to process their events. It is possible that exceptions raised
from handlers fall through to the <code class="code">run</code> call.
<p>
After the exception is caught and processed, the event loop
can be restarted.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALis_running"></a>is_running : <code class="type"><a href="Unixqueue.event_system.html">event_system</a> -> bool</code></pre><div class="info">
Whether the event loop is running<br>
</div>
<pre><span class="keyword">val</span> <a name="VALonce"></a>once : <code class="type"><a href="Unixqueue.event_system.html">event_system</a> -> <a href="Unixqueue.html#TYPEgroup">group</a> -> float -> (unit -> unit) -> unit</code></pre><div class="info">
Arranges that the callback function is called once after the
passed period of time (the <code class="code">float</code> argument) has elapsed.
<p>
The arrangement is member of the passed group. By clearing the
group, the timer is deleted, too.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALexn_log"></a>exn_log : <code class="type"><a href="Unixqueue.event_system.html">event_system</a> -><br> ?suppressed:bool -><br> ?to_string:(exn -> string) -> ?label:string -> exn -> unit</code></pre><div class="info">
Exceptions log: In event-based programming, it is sometimes not
possible to handle exceptions appropriately. It is also bad not
to handle them at all. For these cases, the exceptions log might
be an alternative: Instead of letting exceptions fall through to
the caller in an uncoordinated way, it is better to catch them
at the right moment, and to log them for further analysis.
<p>
By default, <code class="code">exn_log</code> does nothing. In debug mode, however, the
exceptions are reported as part of the debug log.
<p>
<b>Example:</b> A typical candidate for the exceptions log are
cleanup actions within exception handlers, e.g.
<p>
<pre><code class="code">try ...
with Processing_error ->
try
cleanup(); (* e.g. close file descriptors *)
...
with nested_error ->
Unixqueue.exn_log ~suppressed:true nested_error
</code></pre>
<p>
This is especially useful when the processing error is likely
to cause follow-up errors in the cleanup action. For normal
operation, one can ignore such errors, but for debugging it is
very useful to know that these exceptions happen.
<p>
<br>
</div>
<div class="param_info"><code class="code">suppressed</code> : This flag indicates that the exception is not
re-raised after logging. Just a hint for debugging. Default
is <code class="code">false</code>.</div>
<div class="param_info"><code class="code">to_string</code> : This function is called to convert the exception
into a printable string. Default is <code class="code">Printexc.to_string</code>.</div>
<div class="param_info"><code class="code">label</code> : The label is included in the log output. This is
useful to describe where the log message is generated.</div>
<pre><span class="keyword">val</span> <a name="VALdebug_log"></a>debug_log : <code class="type"><a href="Unixqueue.event_system.html">event_system</a> -> ?label:string -> string -> unit</code></pre><div class="info">
Outputs a message in the debug log (when enabled).
<p>
<br>
</div>
<div class="param_info"><code class="code">label</code> : The label is included in the log output. This is
useful to describe where the log message is generated.</div>
<pre><span class="keyword">val</span> <a name="VALset_debug_mode"></a>set_debug_mode : <code class="type">bool -> unit</code></pre><div class="info">
Whether to output debug messages. Output goes to stderr.
Setting the debug mode implies setting Equeue's debug mode.
<p>
The debug messages may really help debugging event systems.
Unfortunately, some understanding of the internal processing
is required to interpret debug protocols.<br>
</div>
</body></html>
|
