<!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>
