module Unixqueue: sig end
Unix.select
function. The idea is to have
an event queue (implemented by Equeue
) that manages all file events that
can be watched by a Unix.select
call. As event 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.
These events are queued up, and they are presented to event handlers that may process them.
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.
Unix.select
function. The idea is to have
an event queue (implemented by Equeue
) that manages all file events that
can be watched by a Unix.select
call. As event 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.
These events are queued up, and they are presented to event handlers that may process them.
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.
THREAD-SAFETY
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 Unixqueue_mt
.
Note that the underlying Equeue
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.)
The TCL extension is not thread-safe.
type
group
exception Abort of (group * exn)
First argument is the group. The second argument
is an arbitrary exception (must not be Abort
again) which is
passed to the abort action.
type
wait_id
operation
.type
operation =
| |
Wait_in of |
(* | wait for input data | *) |
| |
Wait_out of |
(* | wait until output can be written | *) |
| |
Wait_oob of |
(* | wait for out-of-band data | *) |
| |
Wait of |
(* | wait only for timeout | *) |
operation
specifies the condition to wait for. Every kind
of operation may have an associated timer (not only Wait
).type
event =
| |
Input_arrived of |
(* | Input data has arrived | *) |
| |
Output_readiness of |
(* | Output is possible now | *) |
| |
Out_of_band of |
(* | OOB data has arrived | *) |
| |
Timeout of |
(* | A timer has expired | *) |
| |
Signal |
(* | A signal has happened | *) |
| |
Extra of |
(* | User-generated event | *) |
event
is triggered when the condition of an operation
becomes true, when a signal happens, or when the event is
(artificially) added to the event queue (add_event
, below).
The events resulting from an operation
carry the group of
the resource with them.
The event Signal
is triggered when the EINTR
condition is
caught; this normally means that a signal has just been delivered.
The generation of Signal
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 EINTR
condition and not the Unixqueue
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 Signal
.
The event Extra
can only be artificially added to the queue,
and the argument of Extra
is an exception value that distinguishes
between several kinds of user-generated events.
type
event_system
event_system
manages events, handlers, resources, groups,
etc.
A resource is an operation with an optional timer. The operation
describes the condition to watch for, and the timer defines the
maximum period of time for that. If the condition becomes true,
an Input_arrived
, Output_readiness
, or Out_of_band
event
will be triggered. If the timer expires, a Timeout
event will be
generated. After the event the resource remains active, and the
timeout period begins anew.
A resource is usually bound to a file descriptor. It is allowed to watch the same descriptor for several different conditions, but it is forbidden to watch the same descriptor for the same kind of condition several times.
As a special case, the operation Wait
is not bound to a
file descriptor, but simply starts a timer. The argument of Wait
can be used to distinguish between several timers that are active
at the same time.
Event handlers get the events one after the other, and
process them. When a handler is called for an event, there are
several possible reactions: (1) The handler can return normally,
which means that the event has been accepted, and will not be
passed to any other handler. (2) The handler can raise
Equeue.Reject
, which means that the handler cannot process
the event, and that another handler should get it. (3) The handler
can raise Equeue.Terminate
which means that the event has been
accepted, and that the handler is terminated (it will never be
called again). (4) The handler can raise Abort
which means that
the event is deferred, and that a special abort mechanism is
triggered (see the description for Abort
above), this is also
terminates the handler. The deferred event will again be processed
in the future. (5) The handler can raise any other exception.
This causes that the event is deferred, and the exception falls
through to the caller of run
.
Groups are used to simplify the association of events to
handlers, and to simplify the termination of handlers (see clear
).
If an event is associated with a group, only handlers associated with
the same group will get them.
There is a special Close handler which is useful to close file
descriptors no longer needed. It is called when all resources are
removed from the event system dealing with the file descriptor.
The close handler should close the descriptor. Note that close handlers
are only useful under certain circumstances.
val create_unix_event_system : unit -> event_system
val new_group : event_system -> group
val new_wait_id : event_system -> wait_id
val exists_resource : event_system -> operation -> bool
val add_resource : event_system ->
group -> operation * float -> unit
operation
for the period given by the float
number.
A negative number means that the resource is watched for an infinite
period. The resource becomes a member of the group
.
You cannot add the same operation several times; if you try it the second operation is silently dropped.
The resource remains even if it has generated an event. The timeout
period starts again in this case.
val add_close_action : event_system ->
group -> Unix.file_descr * (Unix.file_descr -> unit) -> unit
This may be useful if the descriptor can be closed in this case.
The close action becomes member of the passed group
. The only
effect of this is that the action is removed when the clear
function
is called.
You can only add (set) one close action for every descriptor.
val add_abort_action : event_system ->
group -> (group -> exn -> unit) -> unit
Abort(g,exn)
where
g
is the group the abort action is member of. In this case,
the callback function is invoked with the group and exn
as
arguments. After that, the group is cleared.
You can only add (set) one abort action for every group.
val remove_resource : event_system -> group -> operation -> unit
Not_found
will be raised.
The removal of resources may trigger close actions.
val add_handler : event_system ->
group ->
(event_system ->
event Equeue.t -> event -> unit) ->
unit
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.
val add_event : event_system -> event -> unit
val clear : event_system -> group -> unit
When a group is terminated, it is not allowed to refer to the
group any longer. Functions will raise Invalid_argument
if this
is tried nevertheless.
val run : event_system -> unit
The event loop returns normally when there are not any resources
and not any events in the queue. The loop raises
Equeue.Out_of_handlers
if there are resources but no handlers
to process their events. It is possible that exceptions raised
from handlers fall through to the run
call.
After the exception is caught and processed, the event loop
can be restarted.
val once : event_system -> group -> float -> (unit -> unit) -> unit
float
argument) has elapsed.
The arrangement is member of the passed group. By clearing the
group, the timer is deleted, too.
val set_debug_mode : bool -> unit
The debug messages may really help debugging event systems.
Unfortunately, some understanding of the internal processing
is required to interpret debug protocols.
val attach_to_tcl_queue : event_system -> (event_system -> unit) -> unit
attach_to_tcl_queue es runner
:
The event system es
is attached to the central Tcl-8.0 event queue.
This function is only available if equeue is compiled for use
with Tcl/Tk; if not you will get a Failure("Unixqueue.attach_to_tcl_queue")
.
This function is an extension to run
if unixqueues are used together
with Tcl/Tk. Both Unixqueue and Tcl provide event queues for system events,
and it is possible to merge both queues such that events may happen and
be processed on one queue while the other queue blocks.
attach_to_tcl_queue
returns immediately, but sets up a Tcl event source
such that Tcl informs Unixqueue when events on interesting resources happen.
After attach_to_tcl_queue
has been invoked, you may continue with the
Tcl main event loop. Once events happen the event system es
is waiting
for, the function runner
is called with es
as argument. runner
should invoke run
, and catch any exceptions and handle them. Before
runner
returns to the caller, all events on es
should have been
processed; es
should then be empty. (If not, these events simply
remain on the queue, and they will be processed again when the next new
event coming from a resource is added.)
If this function is called, and the event system is already attached, nothing happens.
Of course, this is all intended to help writing applications which have
a graphical user interface (GUI) built with labltk, and some network
functionality which is designed to work in the background. Simply create
your GUI with labltk, and once the button is pressed which starts the
network I/O, you call attach_to_tcl_queue
, and the I/O will be processed
concurrently with any user input coming from the GUI.
Note: attach_to_tcl_queue
is not thread-safe.