2
* $Id: unixqueue.mli 459 2006-04-30 19:49:19Z gerd $
2
* $Id: unixqueue.mli 1616 2011-06-10 15:08:57Z gerd $
8
(**********************************************************************)
10
(**********************************************************************)
12
(* written by Gerd Stolpmann *)
14
(** This module generalizes the [Unix.select] function. The idea is to have
15
* an event queue (implemented by {!Equeue}) that manages all file events that
16
* can be watched by a [Unix.select] call. As {b event} is considered when there
17
* is something to do for a file descriptor (reading, writing, accepting
18
* out-of-band data), but also the condition that for a certain period
19
* of time ("timeout") nothing
20
* has happened. Furthermore, a signal is also considered as an event,
21
* and it is also possible to have user-generated extra events.
23
* These events are queued up, and they are presented to event handlers
24
* that may process them.
26
* You can describe what types of event conditions are watched by adding
27
* "resources". You can think a resource being a condition (bound to
28
* a real resource of the operating system) for which
29
* events are generated if the condition becomes true.
34
* Since release 1.2 of Equeue, this module serializes automatically.
35
* You can call functions for the same event system from different
36
* threads. This requires some special initialization, see {!Unixqueue_mt}.
38
* Note that the underlying {!Equeue} module is reentrant, but not
39
* serializing. (It is not recommended (and not necessary) to call
40
* functions of the Equeue module directly in multi-threaded programs.)
42
* The TCL extension is not thread-safe.
8
(** Unixqueues are one of the two forms of system event loops provided
9
by Ocamlnet. Besides Unixqueue, there is also pollset (see
10
{!Netsys_pollset}). The pollsets are much simpler (there is no
11
queuing of events), and nowadays Unixqueue bases upon pollset,
12
and extends its functionality. Historically, however, Unixqueue
13
precede pollset, and there are still implementations of the former
14
in Ocamlnet not using pollset as its base data structure.
16
The common idea of both data structures is the generalization of
17
watching for events, as it is also provided by the [Unix.select]
18
function. Note, however, that recent implementations no longer
19
use [Unix.select], but better system interfaces for the same.
21
When there is something to do for a file descriptor (reading,
22
writing, accepting out-of-band data), this is called an {b event},
23
and the task of Unixqueue is to check when events happen, and to
24
tell some consumer about the events.
26
There are three further types of events: Timeout events, signal
27
events, and user-defined events.
29
The events are queued up, and they are presented to event handlers
30
that may process them.
32
You can describe what types of event conditions are watched by adding
33
{b resources}. You can think a resource being a condition (bound to
34
a real resource of the operating system) for which
35
events are generated if the condition becomes true. Currently, only
36
file descriptors and timers are supported as resources.
39
(** {b Relation to other modules.} This module is thought as the primary
40
interface to Unixqueues. If there isn't any specialty one has to deal
41
with, just use this module:
43
- It defines all required types like [group], [wait_id], etc. Note that
44
these types are reexported from [Unixqueue_util]. Please consider
45
this as implementation detail, and don't use it in your code.
46
- It defines a standard implementation [standard_event_system], which
47
is a good default implementation, although it might not be the best
48
available for all purposes.
49
- It defines a set of access functions like [add_event] which
50
simply call the methods of the event system object of the same name.
51
Note that these functions work for all event system implementation,
52
not only for [standard_event_system].
54
There are further modules that have to do with Unixqueue:
56
- {!Unixqueue_pollset} is the implementation behind
57
[standard_event_system]. If you want to use other pollsets than
58
the standard one, it is possible to create Unixqueues on top of these
59
by using this module directly.
60
- {!Unixqueue_select} is the historic default implementation. It
61
calls directly [Unix.select]. It is still available because it
62
serves as a reference implementation for now.
63
- [Unixqueue_util] is an internal module with implementation details.
64
Please don't call it directly.
65
- {!Uq_gtk} is an implementation of Unixqueue mapping to the
66
GTK event loop. Useful for multiplexing event-based I/O and
67
GTK graphics operations.
68
- {!Uq_tcl} is an implementation of Unixqueue mapping to the
69
TCL event loop. Useful for multiplexing event-based I/O and
70
event-based code written in TCL (especially TK).
73
(** {b Thread safety.} The default implementation of Unixqueue is
74
thread-safe, and operations can be called from different threads.
75
For other implementations, please look at the modules implementing
80
(** {1 Types and exceptions} *)
83
type group = Unixqueue_util.group
46
84
(** A group is an abstract tag for a set of events, resources, and
47
85
* event handlers. Usually every event handler creates a new group,
48
86
* and all events and resources processed by the handler are
229
(** {1 Creating event systems} *)
231
class standard_event_system : unit -> event_system
232
(** The standard implementation of an event system. It uses
233
{!Unixqueue_pollset.pollset_event_system} on top of
234
{!Netsys_pollset_generic.standard_pollset}.
237
val standard_event_system : unit -> event_system
238
(** Create a new, empty, standard event system *)
183
240
class unix_event_system : unit -> event_system
184
(** The standalone implementation of an event system *)
241
(** An alternate name for [standard_event_system], provided for
242
backward compatibility.
186
245
val create_unix_event_system : unit -> event_system
187
(** Create a new, empty event system *)
246
(** An alternate name for [standard_event_system], provided for
247
backward compatibility.
251
(** {1 Using event systems} *)
253
(** The following functions work for all kinds of event systems, not
254
only for the ones returned by [standard_event_system].
189
258
val new_group : event_system -> group
190
259
(** Create a new, empty group for the event system *)
312
405
* group, the timer is deleted, too.
315
val exn_log : event_system ->
408
val weak_once : event_system -> group -> float -> (unit -> unit) -> unit
409
(** Same as [once], but the timer does not keep the event system running
410
if it is the only remaining resource.
413
val epsilon : event_system -> (unit -> unit) -> unit
414
(** The execution of the function is pushed onto the event queue
423
(** This module controls debugging of all [Unixqueue_*] modules *)
425
val enable : bool ref
426
(** Enable {!Netlog} debugging *)
428
val set_debug_mode : bool -> unit
432
val set_debug_target : Equeue.Debug.debug_target -> unit
433
(** Restricts debugging to this target.
438
(** The status of the following functions is currently a bit unclear.
439
When a Ocamlnet-wide logging concept is introduced, these functions
440
probably disappear. They are used by other Ocamlnet modules to
441
implement debug logging.
444
(* val exn_log : event_system ->
316
445
?suppressed:bool -> ?to_string:(exn -> string) ->
317
?label:string -> exn -> unit
446
?label:string -> exn -> unit *)
318
447
(** Exceptions log: In event-based programming, it is sometimes not
319
448
* possible to handle exceptions appropriately. It is also bad not
320
449
* to handle them at all. For these cases, the exceptions log might
added
removed
src/equeue/unixqueue.mli
