module Unixqueue:sig
..end
Netsys_pollset
). The pollsets are much simpler (there is no
queuing of events), and nowadays Unixqueue bases upon pollset,
and extends its functionality. Historically, however, Unixqueue
precede pollset, and there are still implementations of the former
in Ocamlnet not using pollset as its base data structure.
The common idea of both data structures is the generalization of
watching for events, as it is also provided by the Unix.select
function. Note, however, that recent implementations no longer
use Unix.select
, but better system interfaces for the same.
When there is something to do for a file descriptor (reading, writing, accepting out-of-band data), this is called an event, and the task of Unixqueue is to check when events happen, and to tell some consumer about the events.
There are three further types of events: Timeout events, signal events, and user-defined events.
The 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. Currently, only
file descriptors and timers are supported as resources.
Netsys_pollset
). The pollsets are much simpler (there is no
queuing of events), and nowadays Unixqueue bases upon pollset,
and extends its functionality. Historically, however, Unixqueue
precede pollset, and there are still implementations of the former
in Ocamlnet not using pollset as its base data structure.
The common idea of both data structures is the generalization of
watching for events, as it is also provided by the Unix.select
function. Note, however, that recent implementations no longer
use Unix.select
, but better system interfaces for the same.
When there is something to do for a file descriptor (reading, writing, accepting out-of-band data), this is called an event, and the task of Unixqueue is to check when events happen, and to tell some consumer about the events.
There are three further types of events: Timeout events, signal events, and user-defined events.
The 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. Currently, only
file descriptors and timers are supported as resources.
Relation to other modules. This module is thought as the primary
interface to Unixqueues. If there isn't any specialty one has to deal
with, just use this module:
group
, wait_id
, etc. Note that
these types are reexported from Unixqueue_util
. Please consider
this as implementation detail, and don't use it in your code.standard_event_system
, which
is a good default implementation, although it might not be the best
available for all purposes.add_event
which
simply call the methods of the event system object of the same name.
Note that these functions work for all event system implementation,
not only for standard_event_system
.
Unixqueue_pollset
is the implementation behind
standard_event_system
. If you want to use other pollsets than
the standard one, it is possible to create Unixqueues on top of these
by using this module directly.Unixqueue_select
is the historic default implementation. It
calls directly Unix.select
. It is still available because it
serves as a reference implementation for now.Unixqueue_util
is an internal module with implementation details.
Please don't call it directly.Uq_gtk
is an implementation of Unixqueue mapping to the
GTK event loop. Useful for multiplexing event-based I/O and
GTK graphics operations.Uq_tcl
is an implementation of Unixqueue mapping to the
TCL event loop. Useful for multiplexing event-based I/O and
event-based code written in TCL (especially TK).typegroup =
Unixqueue_util.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.
Abort handlers are a questionable feature of Unixqueues. You
can also call the clear
operation, and raise the exception
directly. Do not use in new code!
typewait_id =
Unixqueue_util.wait_id
operation
.typeoperation =
Unixqueue_util.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
).typeevent =
Unixqueue_util.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 | *) |
| |
Immediate of |
(* | immediate 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.
The event Immediate(g,f)
also can only be artificially added to
the queue. In contrast to other events, it is not passed to handlers
when the event is processed. Instead, an immediate event is processed
by calling f()
. This is a more direct way of notification, and
it is not necessary to define a handler. Even an immediate event is
member of a group g
, and if the clear
function is called for g
,
the callback function f
will no longer be called.
class type event_system =object
..end
event_system
manages events, handlers, resources, groups,
etc.
class standard_event_system :unit ->
event_system
val standard_event_system : unit -> event_system
class unix_event_system :unit ->
event_system
standard_event_system
, provided for
backward compatibility.
val create_unix_event_system : unit -> event_system
standard_event_system
, provided for
backward compatibility.class performance_event_system :unit ->
event_system
Netsys_pollset_generic.performance_pollset
.
val performance_event_system : unit -> event_system
standard_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_weak_resource : event_system ->
group -> operation * float -> unit
add_resource
, but the resource is weak. Such resources
do not keep the event system running when only weak resources remain.
Normally, Unixqueue.run
returns to the caller not before
all resources are removed and all events are processed. Weak
resources do not count for this condition, i.e. Unixqueue.run
also returns when there are only weak resources left.
As an example, weak resources can be used to time out unused
file descriptors.
Weak resources can be removed with remove_resource
.
New in Ocamlnet 3.
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.
Of course, the idea is to do add_close_action ... Unix.close
. Note
that there is a problem with multi-threaded programs, and this construct
must not be used there. In particular, the close action is called from
remove_resource
or clear
, but it is possible that the event system
is running, so a watched descriptor might be closed. This has undesired
effects. What you should better do is to delay the closure of the
descriptor to a sane moment, e.g. by calling
Unixqueue.once esys g 0.0 (fun () -> Unix.close fd)
from the close action.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 is_running : event_system -> bool
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 weak_once : event_system -> group -> float -> (unit -> unit) -> unit
once
, but the timer does not keep the event system running
if it is the only remaining resource.val epsilon : event_system -> (unit -> unit) -> unit
module Debug:sig
..end