<!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="Uq_gtk.html">
<link rel="next" href="Unixqueue.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 : Equeue</title>
</head>
<body>
<div class="navbar"><a href="Uq_gtk.html">Previous</a>
<a href="index.html">Up</a>
<a href="Unixqueue.html">Next</a>
</div>
<center><h1>Module <a href="type_Equeue.html">Equeue</a></h1></center>
<br>
<pre><span class="keyword">module</span> Equeue: <code class="code">sig</code> <a href="Equeue.html">..</a> <code class="code">end</code></pre><code class="code">Equeue</code> implements generic event queues. An <b>event system</b>
consists of an event queue, a list of event handlers, and an
event source. The queue has FIFO semantics, i.e. the first event
is processed next, and new events are appended to its end. When
an event is delivered to an event handler, all handlers are tried
until a handler accepts the event (or the event is dropped if no
such handler can be found). See below how a handler can indicate
whether to accept or reject an event.
<p>
When the queue is empty, the event source is called once. The source
can add events to the queue, in order to continue event processing.
If the queue remains empty, the execution of the event system
stops.<br>
<hr width="100%">
<br>
<b>THREAD SAFETY</b>
<p>
The module can be used in multi-threaded program provided no
event system is shared by several threads, or if so, access to
functions is serialized.<br>
<pre><span class="keyword">type</span> <a name="TYPEt"></a><code class="type">'a</code> t </pre>
<div class="info">
This is the type of an event system with events of type 'a<br>
</div>
<pre><span class="keyword">exception</span> <a name="EXCEPTIONReject"></a>Reject</pre>
<div class="info">
May be raised by event handlers to reject events<br>
</div>
<pre><span class="keyword">exception</span> <a name="EXCEPTIONTerminate"></a>Terminate</pre>
<div class="info">
May be raised by event handlers to accept events while terminating
themselves<br>
</div>
<pre><span class="keyword">exception</span> <a name="EXCEPTIONOut_of_handlers"></a>Out_of_handlers</pre>
<div class="info">
Raised by <code class="code">run</code> when the event source adds new events to the queue
but there are no event handlers to process them<br>
</div>
<pre><span class="keyword">val</span> <a name="VALcreate"></a>create : <code class="type">?string_of_event:('a -> string) -> ('a <a href="Equeue.html#TYPEt">t</a> -> unit) -> 'a <a href="Equeue.html#TYPEt">t</a></code></pre><div class="info">
Creates a new event system that has an event source, but is
otherwise empty. The argument of type <code class="code">'a t -> unit</code> is the
event source. The source can call <code class="code">add_event</code> to put new events
into the queue.
<p>
<br>
</div>
<div class="param_info"><code class="code">string_of_event</code> : Optionally, one can pass a printer for events.
This has only an effect for debugging output.</div>
<pre><span class="keyword">val</span> <a name="VALadd_event"></a>add_event : <code class="type">'a <a href="Equeue.html#TYPEt">t</a> -> 'a -> unit</code></pre><div class="info">
Puts an event into the event queue of the system.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALadd_handler"></a>add_handler : <code class="type">'a <a href="Equeue.html#TYPEt">t</a> -> ('a <a href="Equeue.html#TYPEt">t</a> -> 'a -> unit) -> unit</code></pre><div class="info">
Adds a handler to the list of handlers of the system.
<p>
An event handler is called with the event system and the event as
arguments. The handler can return in various ways:
<p>
<ul>
<li>Return normally: This means that the event is accepted by the
handler. No other handler will be asked to process the event.</li>
<li>Raise <code class="code">Reject</code>: The event is rejected by the handler. The other
handlers are asked to process the event.</li>
<li>Raise <code class="code">Terminate</code>: The event is accepted, but the handler is
terminated, i.e. will never be called again.</li>
<li>Raise another exception: The event is deferred, and will be
processed again in the future, but after the already queued events.
Furthermore, the exception falls through to the caller of
<code class="code">run</code>.</li>
</ul>
The handler can add new events and new event handlers. The latter
will be activated when the next event is processed.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALrun"></a>run : <code class="type">'a <a href="Equeue.html#TYPEt">t</a> -> unit</code></pre><div class="info">
Running a system means that, unless the queue is empty, the events
at the time of the <code class="code">run</code> invocation and all later added events are
gone through. Each event is presented to the handlers until one
handler accepts the event. Events rejected by all handlers are
dropped silently. If there is no pending event the default event
source is called once. If there are still no events the system stops
and returns. If there are events to process but no handlers which
can do them all events are silently dropped, and the default event
source is called once.
<p>
The exception <code class="code">Out_of_handlers</code> is raised if there are events but no
handlers after the event source has been called. This is considered
as a programming error, and would cause infinite looping if not
detected.
<p>
Note that there is an implicit order among the handlers which is
simply the order the handlers have been added to the system. This
means that you can set a fallback handler which catches any unprocessed
event by adding it last.
<p>
Note that the events are processed in the order they happen. There
is no mechanism to assign priorities to events.
<p>
Handlers are allowed to raise arbitrary exceptions. Exceptions other
than Reject and Terminate are not caught, so the caller has to do this
if appropriate. It is possible to restart an event system by just
calling <code class="code">run</code> again.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALis_running"></a>is_running : <code class="type">'a <a href="Equeue.html#TYPEt">t</a> -> bool</code></pre><div class="info">
Returns whether the event loop is active<br>
</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">
Enables or disables debug mode. Output goes to stderr.<br>
</div>
</body></html>
